@cursor/july 0.1.102 → 0.1.104

package/src/channels/issues/issues-channel.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { createFactoryResourceChannel } from "../../internal/factory-resource-channel.js";
+import type { ChannelDefinition } from "../../types.js";
+import {
+  ISSUE_CREATED_EVENT_TYPE,
+  type IssueCreatedEvent,
+  type IssuesChannelOptions,
+} from "./types.js";
+
+const issueResourceSchema = z
+  .object({
+    name: z.string().min(1),
+    title: z.string().min(1),
+    body: z.string().min(1),
+    state: z
+      .enum(["STATE_UNSPECIFIED", "STATE_OPEN", "STATE_CLOSED"])
+      .optional(),
+    createTime: z.string().min(1).optional(),
+    updateTime: z.string().min(1).optional(),
+    path: z.string().optional(),
+    etag: z.string().optional(),
+  })
+  .passthrough();
+
+const issueCreatedEventSchema: z.ZodType<IssueCreatedEvent> = z.object({
+  eventId: z.string().min(1),
+  eventType: z.literal(ISSUE_CREATED_EVENT_TYPE),
+  teamId: z.string().min(1),
+  occurredAtMs: z.number().int().nonnegative(),
+  issue: issueResourceSchema,
+});
+
+const pack = createFactoryResourceChannel({
+  kind: "issues",
+  eventTypes: [ISSUE_CREATED_EVENT_TYPE],
+  eventSchema: issueCreatedEventSchema,
+  replayDescription: "Replay a Factory issue-created event.",
+  invalidError: "invalid issue event",
+});
+
+export function issuesChannel(
+  options: IssuesChannelOptions
+): ChannelDefinition {
+  return pack.channel(options);
+}
+
+export function getIssuesChannelOptions(
+  definition: object
+): IssuesChannelOptions | undefined {
+  return pack.getOptions(definition);
+}

package/src/channels/issues/types.ts

@@ -0,0 +1,41 @@
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
+import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
+
+export const ISSUE_CREATED_EVENT_TYPE = "issue.created" as const;
+
+export type IssueCreatedEventType = typeof ISSUE_CREATED_EVENT_TYPE;
+
+export type IssueState = "STATE_UNSPECIFIED" | "STATE_OPEN" | "STATE_CLOSED";
+
+/** Factory Issue JSON (camelCase proto JSON). */
+export type IssueResource = {
+  name: string;
+  title: string;
+  body: string;
+  state?: IssueState;
+  createTime?: string;
+  updateTime?: string;
+  path?: string;
+  etag?: string;
+};
+
+/** Factory `issue.created` for every Issue create. */
+export type IssueCreatedEvent = {
+  eventId: string;
+  eventType: IssueCreatedEventType;
+  teamId: string;
+  occurredAtMs: number;
+  issue: IssueResource;
+};
+
+export type IssuesChannelOptions = {
+  onEvent: (
+    event: IssueCreatedEvent,
+    args: ChannelHandlerArgs
+  ) => Promise<unknown> | unknown;
+  continuation?: ContinuationIdentity;
+  path?: string;
+  auth?: ChannelDefinition["auth"];
+  onStart?: ChannelDefinition["onStart"];
+  onStop?: ChannelDefinition["onStop"];
+};

package/src/channels/origin/api.ts

@@ -248,8 +248,10 @@ export type CursorSessionTokenProvider = OriginTokenProvider & {
  * by the deployment's team (`agent-serve` allowlist). Local runs work the
  * same way with a personal key: Origin authorizes the user principal.
  *
- * The API key is re-read on every mint so Bind can drop
- * `CURSOR_API_KEY_FILE` onto a listening process; sessions are cached until
+ * The API key is resolved on every mint so a task-time bind reaches a
+ * listening process without a restart — hosted deliveries consume the bind
+ * file into `CURSOR_API_KEY` before authored work, so this resolve reads env.
+ * Sessions are cached until
  * shortly before their JWT expiry. The cache is **process-wide**, keyed by
  * (endpoint, API key): hosted channels build a fresh `createOriginClient()`
  * per event, so a per-provider cache would re-exchange on every read/write

package/src/channels/origin/origin-channel.ts

@@ -6,11 +6,17 @@ import {
   loopbackOnly,
   POST,
 } from "../../channels.js";
+import {
+  acknowledgeTask,
+  isTaskDispatch,
+  skipped,
+  turnStarted,
+  withPropagatingBackgroundErrors,
+} from "../../internal/channel-dispatch.js";
 import {
   continuationSource,
   normalizeIdentity,
 } from "../../internal/continuation-identity.js";
-import { isDeferredChannelSession } from "../../internal/deferred-channel-session.js";
 import { isDevMode } from "../../internal/dev-mode.js";
 import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
 import { bindLocalIngressSend } from "../../internal/local-ingress.js";
@@ -49,7 +55,6 @@ import type {
   OriginPullRequestEvent,
   OriginRepositoryRef,
   OriginReview,
-  OriginTaskDispatch,
   OriginTurnDispatch,
   OriginWebhookEnvelope,
 } from "./types.js";
@@ -425,12 +430,6 @@ export function defaultOriginPullRequestDispatch(
   return { auth: defaultOriginAuth(ctx) };
 }
 
-function isTaskDispatch(
-  dispatch: OriginDispatch
-): dispatch is OriginTaskDispatch {
-  return "task" in dispatch;
-}
-
 function enrichEventContext(input: {
   ctx: Omit<OriginEventContext, "host" | "artifacts" | "origin">;
   args: ChannelHandlerArgs;
@@ -452,60 +451,6 @@ function enrichEventContext(input: {
   };
 }
 
-export type OriginDispatchOutcome = "skip" | "send" | "task";
-
-const dispatchOutcomeByResponse = new WeakMap<
-  Response,
-  OriginDispatchOutcome
->();
-
-function withDispatchOutcome(
-  response: Response,
-  outcome: OriginDispatchOutcome
-): Response {
-  dispatchOutcomeByResponse.set(response, outcome);
-  return response;
-}
-
-export function getOriginDispatchOutcome(
-  response: Response
-): OriginDispatchOutcome | undefined {
-  return dispatchOutcomeByResponse.get(response);
-}
-
-function skipped(
-  reason: string,
-  extra: Record<string, unknown> = {}
-): Response {
-  return withDispatchOutcome(
-    Response.json({ ok: true, skipped: true, reason, ...extra }),
-    "skip"
-  );
-}
-
-function acknowledgeTask(
-  args: ChannelHandlerArgs,
-  dispatch: OriginTaskDispatch,
-  extra: Record<string, unknown>
-): Response {
-  args.waitUntil(
-    new Promise<void>((resolve, reject) => {
-      setImmediate(() => {
-        Promise.resolve()
-          .then(dispatch.task)
-          .then(() => resolve(), reject);
-      });
-    })
-  );
-  return withDispatchOutcome(
-    Response.json(
-      { ok: true, dispatched: true, mode: "task", ...extra },
-      { status: 202 }
-    ),
-    "task"
-  );
-}
-
 async function startTurn(input: {
   options: OriginChannelOptions;
   args: ChannelHandlerArgs;
@@ -528,26 +473,7 @@ async function startTurn(input: {
     // reply delivery targets the latest wake, not the session's first.
     refreshState: input.state as unknown as JsonValue,
   });
-  if (isDeferredChannelSession(session)) {
-    // Hosted admission captured the send; the control plane allocates the
-    // session after acknowledgement, so there is nothing to report yet.
-    return withDispatchOutcome(
-      Response.json(
-        { ok: true, dispatched: true, mode: "turn" },
-        { status: 202 }
-      ),
-      "send"
-    );
-  }
-  return withDispatchOutcome(
-    Response.json({
-      ok: true,
-      sessionId: session.id,
-      isNew: session.isNew,
-      continuationToken: session.continuationToken,
-    }),
-    "send"
-  );
+  return turnStarted(session);
 }
 
 async function resolveCloudOptions(
@@ -590,7 +516,12 @@ async function applyDispatch(input: {
     return skipped("not_dispatched", input.extra);
   }
   if (isTaskDispatch(input.dispatch)) {
-    return acknowledgeTask(input.args, input.dispatch, input.extra);
+    return acknowledgeTask(
+      input.args,
+      ORIGIN_CHANNEL_KIND,
+      input.dispatch,
+      input.extra
+    );
   }
   const message = [
     input.dispatch.message ?? input.message,
@@ -615,13 +546,10 @@ async function applyDispatch(input: {
 }
 
 /**
- * Core Origin webhook dispatch used by {@link originChannel} routes and by
- * {@link handleAgentServeTrigger} fan-out. Signature verification is the
- * caller's responsibility (HTTP route verifies; internal fan-out skips).
- */
-/**
- * Run authored Origin hooks and `send()`. Does not extract a v2 mailbox —
- * the local CP (or hosted verified ingress) stamps before this runs.
+ * Run the authored hooks for one Origin delivery and `send()` the turn.
+ * Callers own delivery auth: the HTTP route verifies v1ed and binds the app
+ * id; trigger fan-out and hosted admission arrive verified. The v2 mailbox
+ * is stamped upstream (local CP or hosted ingress), never here.
  */
 export async function dispatchOriginWebhook(input: {
   options: OriginChannelOptions;
@@ -893,6 +821,7 @@ export function originChannel(
   originChannelOptionsByDefinition.set(definition, channelOptions);
   attachHostedAdmissionAdapter(definition, {
     kind: ORIGIN_CHANNEL_KIND,
+    prepareArgs: withPropagatingBackgroundErrors,
     dispatch: async ({ payload, args }) => {
       const envelope = parseOriginWebhookEnvelope(payload);
       if (envelope === null) {
@@ -907,10 +836,6 @@ export function originChannel(
         args,
       });
     },
-    getOutcome: (response) => {
-      const outcome = getOriginDispatchOutcome(response);
-      return outcome === "skip" || outcome === "task" ? outcome : undefined;
-    },
   });
   if (usesCursorAccount) {
     registerOriginCursorAccountRuntime(definition, {

package/src/channels/origin/types.ts

@@ -1,4 +1,4 @@
-import type { ContinuationIdentity } from "../../continuation.js";
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
 import type {
   AgentCloudOptions,
   ArtifactsApi,
@@ -97,7 +97,28 @@ export type OriginTurnDispatch = {
   context?: readonly string[];
 };
 
-export type OriginTaskDispatch = { task: () => Promise<void> };
+/** Bound per-delivery helpers passed to an {@link OriginTaskDispatch.task}. */
+export interface OriginTaskArgs {
+  /**
+   * Start (or resume) a session for this delivery. In hosted admission it
+   * captures the send for the control plane; a send captured at `onStart`
+   * bypasses that capture and is rejected.
+   */
+  send: SendMessageFn;
+  /**
+   * Extend the local delivery's background window past the task promise.
+   * Hosted admission awaits the task promise only.
+   */
+  waitUntil: (promise: Promise<unknown>) => void;
+}
+
+/**
+ * Run a host-side handler after the webhook is acknowledged with a 202.
+ * Zero-argument tasks remain valid.
+ */
+export type OriginTaskDispatch = {
+  task: (args: OriginTaskArgs) => void | Promise<void>;
+};
 
 export type OriginDispatch = OriginTurnDispatch | OriginTaskDispatch;
 

package/src/channels/slack/eval-directive.ts

@@ -16,6 +16,7 @@ import {
   EvalRunConflictError,
   EvalRunEmptyError,
 } from "../../internal/eval-run-store.js";
+import { sleep } from "../../internal/sleep.js";
 import { stripLeadingSlackMentions } from "./stop.js";
 import type { SlackBinding } from "./types.js";
 
@@ -218,12 +219,6 @@ function truncateTyping(status: string): string {
   return `${status.slice(0, TYPING_STATUS_MAX - 1)}…`;
 }
 
-async function sleep(ms: number): Promise<void> {
-  await new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
 async function safeTyping(
   binding: SlackBinding,
   status: string

package/src/channels/slack/init.ts

@@ -8,7 +8,10 @@
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { PACKAGE_NAME } from "../../internal/distribution.js";
+import {
+  CLI_COMMAND_NAME as CLI,
+  PACKAGE_NAME,
+} from "../../internal/distribution.js";
 import { writeSlackCliProject } from "./cli-project.js";
 import { envPrefixFromName, slackEnvKeys } from "./credentials.js";
 import {
@@ -91,8 +94,8 @@ function slackChannelSource(
       : ` * Tokens: ${target.envKeys.bot} + ${target.envKeys.app}`;
   const setupLine =
     kind === "manual"
-      ? " * Full setup: agent-serve slack setup"
-      : " * Full setup: agent-serve slack create --dir .";
+      ? ` * Full setup: ${CLI} slack setup`
+      : ` * Full setup: ${CLI} slack create --dir .`;
   return `import { slackChannel } from "${PACKAGE_NAME}/channels/slack";
 
 /**

package/src/channels/slack/setup.ts

@@ -1,5 +1,6 @@
+import { CLI_COMMAND_NAME as CLI } from "../../internal/distribution.js";
 /**
- * Slack setup guide printed by `agent-serve slack setup`.
+ * Slack setup guide printed by `agent-sdk slack setup`.
  *
  * Dedicated Socket Mode app via `slack create` (dashboard wizard).
  * `slack init --manual` is the unmanaged Slack CLI / paste path.
@@ -20,7 +21,7 @@ export const SLACK_SETUP_PHASES: SlackSetupPhase[] = [
     actor: "agent",
     title: "Generate channel + manifests",
     steps: [
-      "agent-serve slack init --manual --dir . --name My Agent",
+      `${CLI} slack init --manual --dir . --name My Agent`,
       "Installs the Slack app when Slack CLI is logged in. Otherwise next asks the user to install it.",
       "Manifests default to Socket Mode (no public Request URL).",
     ],
@@ -55,7 +56,7 @@ export const SLACK_SETUP_PHASES: SlackSetupPhase[] = [
       "Write per-agent tokens into .env.local (see .agent-serve/slack/env.example)",
       "Multi-agent: <PREFIX>_SLACK_BOT_TOKEN + <PREFIX>_SLACK_APP_TOKEN",
       "Single agent: SLACK_BOT_TOKEN + SLACK_APP_TOKEN (--no-prefix)",
-      "agent-serve slack doctor --prefix <PREFIX>",
+      `${CLI} slack doctor --prefix <PREFIX>`,
     ],
   },
   {
@@ -63,7 +64,7 @@ export const SLACK_SETUP_PHASES: SlackSetupPhase[] = [
     actor: "agent",
     title: "Serve",
     steps: [
-      "agent-serve serve --dir . --dev",
+      `${CLI} serve --dir . --dev`,
       "Confirm log: [agent-sdk/slack] Socket Mode connected",
     ],
   },
@@ -103,10 +104,10 @@ export function initialSlackSetupStatus(options: {
 
 export function formatSlackSetupGuide(): string {
   const lines: string[] = [
-    "agent-serve — Slack setup",
+    `${CLI} — Slack setup`,
     "",
     "Dedicated Slack app (Socket Mode) via the dashboard wizard:",
-    "  agent-serve slack create --dir .",
+    `  ${CLI} slack create --dir .`,
     "  Finish Slack consent and the bot name there. The CLI writes",
     "  tokens into .env.local.",
     "",

package/src/channels/slack/types.ts

@@ -2,7 +2,7 @@
  * Types for the Slack platform channel pack.
  */
 
-import type { ContinuationIdentity } from "../../continuation.js";
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
 import type {
   AgentCloudOptions,
   ArtifactsApi,

package/src/channels.ts

@@ -103,7 +103,6 @@ export type {
   ChannelRoute,
   ChannelRouteHandler,
   ChannelRouteSchema,
-  ChannelRouteSpec,
   ChannelSession,
   ChannelStartArgs,
   HttpChannelConfig,

package/src/client.ts

@@ -1,5 +1,5 @@
 /**
- * Client-side plumbing for talking to a running agent-serve deployment:
+ * Client-side plumbing for talking to a running agent-sdk deployment:
  * production target resolution (stored Cursor login → engineAccess URL and
  * headers), request-header assembly, and the sessions listing used for
  * latest-session binding.

package/src/connections.ts

@@ -65,7 +65,7 @@
  * 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-serve login` or `CURSOR_API_KEY`):
+ * to be signed in (`agent-sdk login` or `CURSOR_API_KEY`):
  *
  * ```ts
  * // agent/mcp-connections/account.ts — every connected server (no allowlist)

package/src/evals.ts

@@ -215,7 +215,7 @@ export interface EvalTestContext extends EvalAssertions {
    * change the exit code. Call it before sending messages.
    */
   skip(reason: string): never;
-  /** Debug line (surfaced under `agent-serve eval --verbose`). */
+  /** Debug line (surfaced under `agent-sdk eval --verbose`). */
   log(message: string): void;
   /**
    * Structured score for the playground (and CLI). Values appear on the

package/src/extensions.ts

@@ -2,8 +2,11 @@
  * Extensions — agent-shaped trees an agent mounts under a namespace.
  *
  * An extension is a directory laid out like `agent/`: `extension.ts`
- * declares it, `tools/<name>.ts` and `skills/<name>.md|ts` are its
- * contributions, `lib/` holds shared code.
+ * declares it; `tools/`, `skills/`, `mcp-connections/`,
+ * `host-connections/`, `hooks/`, `channels/`, `schedules/`,
+ * `subagents/`, `instructions`, `ab.ts` / `ab/`, `artifacts.ts`,
+ * and `sandbox/workspace/` are its contributions. `lib/` holds
+ * shared code.
  *
  * ```ts
  * // extension.ts
@@ -27,8 +30,7 @@
  *
  * A consumer mounts it from `agent/extensions/<ns>.ts`; the filename is the
  * namespace, and every contribution is exposed as `<ns>__<name>`
- * (`ci__failed_jobs`). `__` is reserved for that: an authored `agent/tools/`
- * or `agent/skills/` name may not contain it.
+ * (`ci__failed_jobs`). `__` is reserved for that.
  *
  * ```ts
  * // agent/extensions/ci.ts
@@ -40,7 +42,8 @@
  * To adjust a contribution, mount as a directory instead and overlay the
  * slot: `agent/extensions/ci/extension.ts` holds the mount, and
  * `agent/extensions/ci/tools/job_log.ts` replaces `ci__job_log` — or removes
- * it with `export default disableTool()`.
+ * it with `export default disableTool()`, `disableSkill()`, or the
+ * matching helper for that slot.
  *
  * A Cursor plugin (the marketplace format: `.cursor-plugin/plugin.json`,
  * `skills/`, `commands/`, `agents/`, `mcp.json`) mounts the same way with
@@ -69,6 +72,7 @@ import { brandDefinition } from "./internal/brand.js";
 import type {
   CursorPluginOptions,
   DisabledConnectionDefinition,
+  DisabledDefinition,
   DisabledToolDefinition,
   Extension,
   ExtensionMount,
@@ -79,6 +83,7 @@ export type {
   CursorPluginDeclaration,
   CursorPluginOptions,
   DisabledConnectionDefinition,
+  DisabledDefinition,
   DisabledToolDefinition,
   DiscoveredExtension,
   Extension,
@@ -128,6 +133,43 @@ export function disableConnection(): DisabledConnectionDefinition {
   return brandDefinition("disabled-connection", {});
 }
 
+/** Remove an extension contribution from a directory overlay. */
+export function disable(): DisabledDefinition {
+  return brandDefinition("disabled", {});
+}
+
+export function disableSkill(): DisabledDefinition {
+  return disable();
+}
+
+export function disableHook(): DisabledDefinition {
+  return disable();
+}
+
+export function disableChannel(): DisabledDefinition {
+  return disable();
+}
+
+export function disableSchedule(): DisabledDefinition {
+  return disable();
+}
+
+export function disableSubagent(): DisabledDefinition {
+  return disable();
+}
+
+export function disableInstructions(): DisabledDefinition {
+  return disable();
+}
+
+export function disableAB(): DisabledDefinition {
+  return disable();
+}
+
+export function disableArtifacts(): DisabledDefinition {
+  return disable();
+}
+
 export function cursorPlugin(options: CursorPluginOptions): ExtensionMount {
   return brandDefinition("extension", {
     extension: {

package/src/files.ts

@@ -156,12 +156,15 @@ export const AGENT_SERVE_USER_STORE_KEY_PREFIX = "agent-serve";
 /**
  * Framework-owned keys for state that lives on the deployment's Agent Store
  * but is not author `host.files` data: artifact rows and payloads, authored
- * skills synced for cloud turns, and the cross-session memory journal. Kept
- * out of `files/` so author listings never see framework rows.
+ * skills and workspace seeds synced for cloud turns, and the cross-session
+ * memory journal. Kept out of `files/` so author listings never see
+ * framework rows.
  *
  * Skills sit at store-root `skills/<name>/…` so exec-daemon's
  * `--agent-store-skills-dir` walk finds them the same way it finds user-store
- * skills. Memory and artifacts stay under {@link STORAGE_KEY_ROOT}.
+ * skills. Workspace seeds sit at store-root `workspace/…` so the mount path
+ * the first cloud prompt names stays short. Memory and artifacts stay under
+ * {@link STORAGE_KEY_ROOT}.
  */
 function createAgentStoreKeys(root: string) {
   return {
@@ -180,6 +183,14 @@ function createAgentStoreKeys(root: string) {
     /** Personal-key cloud agents: namespaced so they cannot collide with the user's own `skills/`. */
     userSkillsPrefix: (agent: string): string =>
       `${AGENT_SERVE_USER_STORE_KEY_PREFIX}/${agent}/skills/`,
+    workspaceFile: (
+      relPath: string,
+      workspacePrefix: string = "workspace/"
+    ): string => `${workspacePrefix}${relPath}`,
+    workspacePrefix: (): string => "workspace/",
+    /** Personal-key cloud agents: namespaced like {@link userSkillsPrefix}. */
+    userWorkspacePrefix: (agent: string): string =>
+      `${AGENT_SERVE_USER_STORE_KEY_PREFIX}/${agent}/workspace/`,
     memoryDir: (agent: string): string => `${root}/${agent}/memory`,
     memoryJournal: (agent: string): string =>
       `${root}/${agent}/memory/journal.jsonl`,
@@ -213,6 +224,13 @@ export const agentSdkAgentStoreKeys: AgentStoreKeys = createAgentStoreKeys(
  */
 export const DEPLOYMENT_STORE_MOUNT_PATH = "/cursor/stores/deployment";
 
+/**
+ * USER store FUSE mount on personal-key cloud-runtime VMs. Mirrors
+ * `AGENT_STORE_MOUNT_ROOT` / `AGENT_STORE_USER_MOUNT_NAME` in
+ * `@anysphere/constants`.
+ */
+export const USER_STORE_MOUNT_PATH = "/cursor/stores/user";
+
 /** Errors raised by the file surface. Thrown by sinks and by the framework. */
 export class FileConflictError extends Error {
   constructor(