@cursor/july 0.1.107 → 0.1.109

package/src/connections.ts

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

package/src/extensions/improve/extension.ts

@@ -0,0 +1,70 @@
+/**
+ * Self-improvement as an extension. An agent's behaviour is source in a
+ * repository, so changing how it behaves is a change to that source: a
+ * one-off Cursor cloud agent does the coding on a branch and opens a pull
+ * request, the agent that mounted this writes the brief and reports the
+ * pull request, and the tree it runs from is never edited.
+ *
+ * ```ts
+ * // agent/extensions/improve.ts
+ * import improve from "@cursor/july/extensions/improve";
+ *
+ * export default improve({
+ *   repo: "https://github.com/acme/agents",
+ *   path: "agents/concierge",
+ * });
+ * ```
+ *
+ * Contributes the `<namespace>__yourself` skill; mount it as `improve` so
+ * the skill reads `improve__yourself`. The coding goes through the
+ * cursor-cloud-agents extension, so mount that too, with `repo` among its
+ * `cloud.repos`. An agent whose own turns run on a cloud VM with the
+ * repository checked out needs no second mount: the skill has it work in
+ * that checkout.
+ */
+
+import { z } from "zod";
+import { defineExtension } from "../../extensions.js";
+import type { Extension } from "../../types.js";
+
+export interface ImproveOptions {
+  /** Repository that holds the agent's source. One of the cloud agents mount's `cloud.repos`. */
+  repo: string;
+  /** The agent's directory in the repository, as `agent-sdk deploy --path` names it. */
+  path: string;
+  /** Ref the deployment tracks: branches start there and pull requests target it. Defaults to `main`. */
+  ref?: string;
+  /** What a coding agent must know about this tree beyond the Agent SDK layout, one line each. */
+  notes?: string[];
+  /** Who deploys a merged change and when it is live. Defaults to "It takes effect at the next deploy." */
+  deploy?: string;
+}
+
+/** {@link ImproveOptions} with defaults applied. */
+export interface ImproveConfig extends ImproveOptions {
+  ref: string;
+  notes: string[];
+  deploy: string;
+}
+
+const line = z.string().trim().min(1);
+
+const improve: Extension<ImproveConfig, ImproveOptions> = defineExtension({
+  root: import.meta.dirname,
+  description:
+    "Change your own source through a one-off cloud agent and a pull request, never the running tree.",
+  config: z.object({
+    repo: z.string().url(),
+    path: z
+      .string()
+      .regex(
+        /^[^\s/]+(\/[^\s/]+)*$/,
+        "Expected a repository-relative path like agents/concierge"
+      ),
+    ref: line.default("main"),
+    notes: z.array(line).default([]),
+    deploy: line.default("It takes effect at the next deploy."),
+  }),
+});
+
+export default improve;

package/src/extensions/improve/skills/yourself.ts

@@ -0,0 +1,50 @@
+import { defineSkill } from "../../../skills.js";
+import type { SkillDefinition } from "../../../types.js";
+import extension from "../extension.js";
+
+const { repo, path, ref, notes, deploy } = extension.config;
+
+const treeNotes =
+  notes.length === 0
+    ? ""
+    : `\nAbout this tree in particular; copy these into the brief verbatim:\n\n${notes.map((note) => `- ${note}`).join("\n")}\n`;
+
+const yourself: SkillDefinition = defineSkill({
+  description:
+    "Change your own source (instructions, skills, tools, channels, connections, model, deployment) through a one-off Cursor cloud agent and a pull request. Use whenever the ask is about how you yourself behave, including adding or editing a skill, so the change lands in the repository instead of the tree you happen to be running from.",
+  markdown: `# Improve yourself
+
+You are the Agent SDK agent at \`${path}\` in ${repo}, deployed from \`${ref}\`. A change to how you behave is a change to that source, and it goes through the repository like any other change: a branch, a pull request, review, a deploy. Nothing about it is special except that people describe it in the second person.
+
+## What changes where
+
+Under \`${path}/agent/\`:
+
+- \`instructions.md\` is the always-on system prompt: identity, tool-choice rules, the output contract.
+- \`skills/<name>.md\` is a procedure loaded on demand; a \`<name>/SKILL.md\` directory carries sibling files. The \`description\` frontmatter is the routing rule the model sees.
+- \`tools/<name>.ts\` is typed, executable behaviour: anything that must be right every time.
+- \`channels/\`, \`mcp-connections/\`, and \`host-connections/\` are the surfaces and connectors.
+- \`agent.ts\` is the model, its parameters, and the runtime.
+- \`extensions/<ns>.ts\` mounts an extension. This skill arrives through one.
+${treeNotes}
+## The change is made on a clean checkout
+
+Never edit the tree you run from: it is a deployed copy of \`${path}\`, and nothing changed there lasts. The change is made on a clean checkout of ${repo} at \`${ref}\`. When your own turn runs on a cloud VM with that repository checked out, that VM is the checkout: branch there. Otherwise hand the coding to a one-off Cursor cloud agent through the cloud agents extension, with \`launch\` under its mount namespace, \`repo\` set to ${repo}, and \`starting_ref\` to \`${ref}\`. One agent per change; steer it with \`reply\` rather than launching another.
+
+## The brief
+
+Whoever makes the change works from the same brief. For a cloud agent it is the whole handoff, because it cannot see this conversation:
+
+- Who and why. A change to the source of the Agent SDK agent at \`${path}\`, asked for by the person in front of you: the change in their words, and what you know about why they want it.
+- Where. Repository ${repo}, ref \`${ref}\`, directory \`${path}\`, the layout above, and the files you expect to change.
+- How. Follow the repository's own conventions (its \`AGENTS.md\` files and rules along the paths touched). Keep the diff to the change. Run the checks the repository defines for \`${path}\`. Open a pull request against \`${ref}\`; never merge it.
+- Report. The pull request URL, what changed, what was verified and how, and anything left unverified.
+
+## Report
+
+If you launched a cloud agent, give the person its URL with the full id, read its report with \`dump\` (\`get\` for status), and read the pull request before repeating its claims. Report the pull request, not that you delegated.
+
+A merged pull request changes nothing by itself. ${deploy} Never say you have already changed yourself. Editing your own source is still an edit: do it when asked, and stop at the pull request. Deploying is a separate authorization.`,
+});
+
+export default yourself;

package/src/extensions.ts

@@ -4,8 +4,8 @@
  * An extension is a directory laid out like `agent/`: `extension.ts`
  * 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
+ * `subagents/`, `instructions`, `artifacts.ts`, and
+ * `sandbox/workspace/` are its contributions. `lib/` holds
  * shared code.
  *
  * ```ts
@@ -162,10 +162,6 @@ export function disableInstructions(): DisabledDefinition {
   return disable();
 }
 
-export function disableAB(): DisabledDefinition {
-  return disable();
-}
-
 export function disableArtifacts(): DisabledDefinition {
   return disable();
 }

package/src/index.ts

@@ -31,7 +31,6 @@ import type {
   ServeOptions,
 } from "./types.js";
 
-export { defineAB } from "./ab.js";
 export { defineArtifacts } from "./artifacts.js";
 // Authoring helpers (also available on their focused subpath exports).
 export {
@@ -55,7 +54,6 @@ export {
   cursorPlugin,
   defineExtension,
   disable,
-  disableAB,
   disableArtifacts,
   disableChannel,
   disableConnection,
@@ -190,7 +188,6 @@ export { defineSkill } from "./skills.js";
 export type {
   DurableSessionRecord,
   DurableSessionSummary,
-  StorageABTable,
   StorageCasTable,
   StorageConfig,
   StorageContext,

package/src/internal/authored-alias-hooks.ts

@@ -20,10 +20,16 @@
 // Null-prototype copies so specifiers like "constructor" or "__proto__"
 // can never resolve to inherited Object.prototype members.
 let directAliases = toNullProtoMap({});
+let sourceFallbackAliases = toNullProtoMap({});
 let sourceTreeFallbackParentURL: string | undefined;
 
 export interface AuthoredAliasHookData {
   directAliases: Record<string, string>;
+  /**
+   * Framework exports omitted from the running distribution. Resolve these
+   * against an authored project's `anysphere-source` package condition.
+   */
+  sourceFallbackAliases?: string[];
   /**
    * `file:` URL of the running `@cursor/july` package.json. Bare imports
    * from monorepo `packages/agent-serve/` source retry against this parent
@@ -40,6 +46,11 @@ function toNullProtoMap(
 
 export function initialize(data: AuthoredAliasHookData): void {
   directAliases = toNullProtoMap(data.directAliases);
+  sourceFallbackAliases = toNullProtoMap(
+    Object.fromEntries(
+      (data.sourceFallbackAliases ?? []).map((specifier) => [specifier, "1"])
+    )
+  );
   const parent = data.sourceTreeFallbackParentURL;
   sourceTreeFallbackParentURL =
     typeof parent === "string" && parent !== "" ? parent : undefined;
@@ -65,6 +76,9 @@ export function resolve(
   if (direct !== undefined) {
     return { url: direct, shortCircuit: true };
   }
+  if (sourceFallbackAliases[specifier] !== undefined) {
+    return nextResolve(specifier, withCondition(context, "anysphere-source"));
+  }
   if (
     sourceTreeFallbackParentURL !== undefined &&
     isBarePackageSpecifier(specifier) &&
@@ -95,6 +109,24 @@ function withParentURL(context: unknown, parentURL: string): unknown {
   return { parentURL };
 }
 
+function withCondition(context: unknown, condition: string): unknown {
+  const record =
+    context !== null && typeof context === "object"
+      ? (context as Record<string, unknown>)
+      : {};
+  const conditions = Array.isArray(record["conditions"])
+    ? record["conditions"].filter(
+        (value): value is string => typeof value === "string"
+      )
+    : [];
+  return {
+    ...record,
+    conditions: conditions.includes(condition)
+      ? conditions
+      : [...conditions, condition],
+  };
+}
+
 function isBarePackageSpecifier(specifier: string): boolean {
   if (specifier.length === 0) {
     return false;

package/src/internal/authored-loaders.ts

@@ -18,10 +18,11 @@
  * tsconfig paths already cover them.
  */
 
+import { existsSync } from "node:fs";
 import { stat } from "node:fs/promises";
 import { register as registerModuleHooks } from "node:module";
 import { join } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import type { AuthoredAliasHookData } from "./authored-alias-hooks.js";
 import {
   CLI_COMMAND_NAME,
@@ -61,6 +62,22 @@ export function authoredModuleSpecifier(
   return url.href;
 }
 
+export function partitionFrameworkAliases(aliases: Record<string, string>): {
+  directAliases: Record<string, string>;
+  sourceFallbackAliases: string[];
+} {
+  const directAliases: Record<string, string> = {};
+  const sourceFallbackAliases: string[] = [];
+  for (const [specifier, url] of Object.entries(aliases)) {
+    if (existsSync(fileURLToPath(url))) {
+      directAliases[specifier] = url;
+    } else {
+      sourceFallbackAliases.push(specifier);
+    }
+  }
+  return { directAliases, sourceFallbackAliases };
+}
+
 /**
  * Dynamically import an authored TypeScript/JavaScript module, re-reading it
  * from disk when the file's mtime has changed since the last import.
@@ -165,8 +182,15 @@ function registerFrameworkAliases(): void {
     return;
   }
   const hooksUrl = new URL("./authored-alias-hooks.js", import.meta.url);
+  const { directAliases, sourceFallbackAliases } = partitionFrameworkAliases(
+    frameworkAliases()
+  );
   const data: AuthoredAliasHookData = {
-    directAliases: frameworkAliases(),
+    directAliases,
+    // Internal-only exports stay out of the public package. When one is
+    // mounted by an agent in this source checkout, resolve that one import
+    // through the checkout's `anysphere-source` export instead.
+    sourceFallbackAliases,
     // Hosted factory agents relative-import this package's src/ from a
     // monorepo checkout while npm install ran only in the agent directory.
     // Bare specifiers from that tree retry against this package.json.

package/src/internal/builtin-tools/artifacts.ts

@@ -30,7 +30,7 @@ function kindVariant(name: string, schema: z.ZodType | undefined) {
       .min(1)
       .optional()
       .describe(
-        "Stable upsert key: tagging the same key again updates the existing record instead of creating a new one."
+        "Stable key, unique across kinds. Reusing it replaces that record instead of adding a new one."
       ),
   });
 }
@@ -47,10 +47,9 @@ export function tagArtifactTool(config: ArtifactsConfig): ToolDefinition {
     );
   }
   const description = [
-    "Tag a durable artifact: a record of a notable output you produced, kept across sessions and listed for the people supervising this agent. Tag one whenever you finish something worth surfacing durably.",
+    "Tag a finished output as an artifact. Artifacts persist across sessions and are listed for the people supervising this agent.",
     "Kinds:",
     ...kinds.map(([name, kind]) => `- ${name}: ${kind.description}`),
-    "Same `key` upserts: tagging it again updates that record — use a stable key when re-tagging the same underlying thing (e.g. the same PR URL).",
   ].join("\n");
   return defineTool({
     description,

package/src/internal/channel-route-dispatch.ts

@@ -0,0 +1,66 @@
+import type { ChannelHandlerArgs, ChannelRoute } from "../types.js";
+import { jsonResponse } from "./http-channel.js";
+import { validateToolInput } from "./json-schema.js";
+
+/**
+ * Run one authored channel route: validate the declared Zod query / body
+ * schemas onto `handlerArgs`, then call the handler. Shared by the local
+ * router mount and hosted catch replay so a caught request meets exactly
+ * the same schema gate as a direct one.
+ */
+export async function invokeChannelRoute(input: {
+  route: ChannelRoute;
+  request: Request;
+  handlerArgs: ChannelHandlerArgs;
+}): Promise<Response> {
+  const { route, handlerArgs } = input;
+  let request = input.request;
+
+  if (route.querySchema !== undefined) {
+    const rawQuery = Object.fromEntries(
+      new URL(request.url).searchParams.entries()
+    );
+    const queryValidation = validateToolInput(route.querySchema, rawQuery);
+    if (!queryValidation.ok) {
+      return jsonResponse({ error: queryValidation.message }, { status: 400 });
+    }
+    handlerArgs.query = queryValidation.value;
+  }
+
+  if (route.bodySchema !== undefined) {
+    // Buffer once so handlers that need the raw body (e.g. GitHub HMAC) can
+    // still read `request.text()` / `request.json()`.
+    let bodyText: string;
+    try {
+      bodyText = await request.text();
+    } catch {
+      return jsonResponse(
+        { error: "Failed to read request body" },
+        { status: 400 }
+      );
+    }
+    let rawBody: unknown;
+    try {
+      rawBody = bodyText === "" ? {} : JSON.parse(bodyText);
+    } catch {
+      return jsonResponse(
+        { error: "Request body must be valid JSON" },
+        { status: 400 }
+      );
+    }
+    const bodyValidation = validateToolInput(route.bodySchema, rawBody);
+    if (!bodyValidation.ok) {
+      return jsonResponse({ error: bodyValidation.message }, { status: 400 });
+    }
+    handlerArgs.body = bodyValidation.value;
+    request = new Request(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: bodyText === "" ? undefined : bodyText,
+      // node: undici / fetch may require duplex for streamed bodies;
+      // a string body does not.
+    });
+  }
+
+  return route.handler(request, handlerArgs);
+}

package/src/internal/channel-state.ts

@@ -0,0 +1,96 @@
+import { isDeepStrictEqual } from "node:util";
+import type { JsonValue } from "../types.js";
+
+type JsonRecord = Record<string, JsonValue>;
+
+function asRecord(value: JsonValue | undefined): JsonRecord | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as JsonRecord;
+}
+
+/**
+ * Shallow-merge a wake patch into durable channel state. Null / undefined
+ * patch values leave the existing key alone so sticky fields survive.
+ */
+export function mergeChannelStateSkipNull(
+  current: JsonValue | undefined,
+  patch: JsonValue | undefined
+): JsonValue | undefined {
+  if (patch === undefined) {
+    return current;
+  }
+  const currentRecord = asRecord(current);
+  const patchRecord = asRecord(patch);
+  if (currentRecord === undefined || patchRecord === undefined) {
+    return structuredClone(patch);
+  }
+  const merged = { ...currentRecord };
+  for (const [key, value] of Object.entries(patchRecord)) {
+    if (value !== null && value !== undefined) {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+/**
+ * Apply handler mutations made against a turn snapshot without reverting
+ * unchanged fields refreshed by a later delivery. At a changed path, objects
+ * merge recursively, arrays and scalars replace, and deletions win.
+ */
+export function mergeChannelStateMutation(args: {
+  current: JsonValue | undefined;
+  before: JsonValue;
+  after: JsonValue;
+}): JsonValue | undefined {
+  const { current, before, after } = args;
+  if (isDeepStrictEqual(before, after)) {
+    return current;
+  }
+  const currentRecord = asRecord(current);
+  const beforeRecord = asRecord(before);
+  const afterRecord = asRecord(after);
+  if (
+    currentRecord === undefined ||
+    beforeRecord === undefined ||
+    afterRecord === undefined
+  ) {
+    return structuredClone(after);
+  }
+
+  const merged = structuredClone(currentRecord);
+  const keys = new Set([
+    ...Object.keys(beforeRecord),
+    ...Object.keys(afterRecord),
+  ]);
+  for (const key of keys) {
+    const hadBefore = Object.hasOwn(beforeRecord, key);
+    const hasAfter = Object.hasOwn(afterRecord, key);
+    if (
+      hadBefore &&
+      hasAfter &&
+      isDeepStrictEqual(beforeRecord[key], afterRecord[key])
+    ) {
+      continue;
+    }
+    if (!hasAfter) {
+      delete merged[key];
+      continue;
+    }
+    const currentValue = merged[key];
+    const afterValue = afterRecord[key]!;
+    merged[key] =
+      hadBefore ||
+      (asRecord(currentValue) !== undefined &&
+        asRecord(afterValue) !== undefined)
+        ? (mergeChannelStateMutation({
+            current: currentValue,
+            before: hadBefore ? beforeRecord[key]! : {},
+            after: afterValue,
+          }) as JsonValue)
+        : structuredClone(afterValue);
+  }
+  return merged;
+}

package/src/internal/cli-ax.ts

@@ -3,8 +3,7 @@
  *   init / run / trajectory / eval
  *
  * Coding agents get JSON-first output, ephemeral local servers, and
- * filesystem-first evals under evals/ (*.eval.ts). Live A/B metrics
- * (`defineAB` under `agent/ab`) plug into serve — there is no `ab` CLI.
+ * filesystem-first evals under evals/ (*.eval.ts).
  */
 
 import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
@@ -23,6 +22,7 @@ import { lookupSessionContinuation, runChat } from "./chat-client.js";
 import { ensureCursorLogin } from "./cli-cursor.js";
 import { resolveDeployAuth } from "./cli-deploy.js";
 import { resolveApiKey } from "./cursor/credentials.js";
+import { DeployApiError } from "./deploy-client.js";
 import { CLI_COMMAND_NAME, PACKAGE_NAME } from "./distribution.js";
 import {
   discoverEvals,
@@ -53,6 +53,7 @@ import {
   resolveTemplate,
 } from "./init-project.js";
 import { offerInstallCursorSkills } from "./install-cursor-skills.js";
+import { rejectV2ForLegacyCommand } from "./legacy-command-guard.js";
 import { runLogsTail, sanitizeCustomerError } from "./logs-client.js";
 import { mapPool } from "./map-pool.js";
 import { openBrowser } from "./open-browser.js";
@@ -189,6 +190,13 @@ export interface AxCliOptions {
   resume?: boolean;
   /** Abort signal (tests / programmatic stop of `playground` proxy). */
   signal?: AbortSignal;
+  /**
+   * `run --prod` / `session --prod --message`: hosted v2 session start on
+   * the agentsdk control plane. `--dry-run` marks the turn non-mutating;
+   * `--as-of` freezes the session clock at a timezone-bearing instant.
+   */
+  dryRun?: boolean;
+  asOf?: string;
 }
 
 export interface ResolvedAgentTarget {
@@ -594,6 +602,15 @@ export async function cmdChat(options: AxCliOptions): Promise<number> {
 }
 
 export async function cmdRun(options: AxCliOptions): Promise<number> {
+  // Only a v2-shaped request tries the control plane; every v1 `run --prod`
+  // form (multi-turn, continuation token, local session id, --url) keeps its
+  // engine-alias path untouched.
+  if (options.prod === true && hostedSessionRejection(options) === undefined) {
+    const started = await cmdHostedSession(options);
+    if (started !== "fallback") {
+      return started;
+    }
+  }
   const messages = options.messages ?? [];
   if (messages.length === 0) {
     die("Provide --message (repeatable) or --messages-file");
@@ -703,6 +720,74 @@ export async function cmdRun(options: AxCliOptions): Promise<number> {
   }
 }
 
+const HOSTED_SESSION_ID_RE = /^ses_[a-f0-9]{24}$/;
+
+/**
+ * Hosted v2 session start: POST the agentsdk control plane, which hands the
+ * wake to Temporal (no resident engine, no `/engine/*` alias). `--session
+ * ses_…` resumes that exact session; there is no continuation token on
+ * this path. A 404 means the slug is not a v2 control-plane deployment, so
+ * `run --prod` falls back to the v1 engine alias.
+ */
+/** Why these options cannot be a hosted v2 session start, if they cannot. */
+function hostedSessionRejection(options: AxCliOptions): string | undefined {
+  if (options.url !== undefined) {
+    return "--prod session start talks to the agentsdk control plane; do not pass --url";
+  }
+  const messages = options.messages ?? [];
+  if (messages.length !== 1 || messages[0]?.trim() === "") {
+    return "Provide exactly one --message (the wake). Multi-turn runs are local-only.";
+  }
+  if (trimNonEmpty(options.continuationToken) !== undefined) {
+    return "--continuation-token is not a hosted v2 identity; pass --session ses_… to resume a session";
+  }
+  const sessionId = trimNonEmpty(options.sessionId);
+  if (sessionId !== undefined && !HOSTED_SESSION_ID_RE.test(sessionId)) {
+    return `--session must be a hosted session id (ses_…), got ${sessionId}`;
+  }
+  return undefined;
+}
+
+async function cmdHostedSession(
+  options: AxCliOptions
+): Promise<number | "fallback"> {
+  const rejection = hostedSessionRejection(options);
+  if (rejection !== undefined) {
+    die(rejection);
+  }
+  const messages = options.messages ?? [];
+  const sessionId = trimNonEmpty(options.sessionId);
+  const auth = await resolveDeployAuth({
+    team: options.team,
+    apiKey: options.apiKey,
+    fetchImpl: options.fetchImpl,
+  });
+  if (typeof auth === "number") {
+    return auth;
+  }
+  const slug = resolveProdSlug(options);
+  try {
+    const accepted = await auth.client.startSession({
+      teamId: auth.teamId,
+      slug,
+      message: messages[0]!.trim(),
+      sessionId,
+      dryRun: options.dryRun,
+      asOf: options.asOf,
+    });
+    console.log(JSON.stringify(accepted, null, 2));
+    return 0;
+  } catch (error) {
+    if (error instanceof DeployApiError && error.status === 404) {
+      return "fallback";
+    }
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`
+    );
+    return 1;
+  }
+}
+
 /**
  * `agent-sdk call <tool>` — deterministic tool invocation over
  * `POST /v1/tools/:toolName` (ephemeral local server unless --url).
@@ -1727,6 +1812,11 @@ export async function cmdLogs(options: AxCliOptions): Promise<number> {
       if (typeof auth === "number") {
         return auth;
       }
+      await rejectV2ForLegacyCommand({
+        client: auth.client,
+        teamId: auth.teamId,
+        slug,
+      });
       await runLogsTail({
         prod: true,
         dir: options.dir,
@@ -1750,6 +1840,7 @@ export async function cmdLogs(options: AxCliOptions): Promise<number> {
             apiKey: options.apiKey,
             fetchImpl: options.fetchImpl,
             err: () => {},
+            skipLegacyArchitectureCheck: true,
           });
           return { agentUrl: target.agentUrl, headers: target.headers };
         },
@@ -1864,9 +1955,26 @@ export async function cmdSession(
   sessionId: string | undefined,
   options: AxCliOptions
 ): Promise<number> {
+  if (options.prod === true && (options.messages?.length ?? 0) > 0) {
+    // `session --prod [ses_…] --message` is the same hosted start as
+    // `run --prod`, with the positional id as the session to resume. Unlike
+    // `run`, a 404 is an error here: this form is explicitly v2.
+    const started = await cmdHostedSession({
+      ...options,
+      sessionId: trimNonEmpty(sessionId) ?? options.sessionId,
+    });
+    if (started === "fallback") {
+      process.stderr.write(
+        `Hosted session start returned 404 for slug ${resolveProdSlug(options)}: deploy a running AgentSDK v2 agent, or use \`${CLI_COMMAND_NAME} run --prod\` (falls back to the v1 engine).\n`
+      );
+      return 1;
+    }
+    return started;
+  }
   if (sessionId === undefined || sessionId.trim() === "") {
     process.stderr.write(
-      `Usage: ${CLI_COMMAND_NAME} session <sessionId> [--url | --prod] [--json | --text | --events] [--out <file.ndjson>]\n`
+      `Usage: ${CLI_COMMAND_NAME} session <sessionId> [--url | --prod] [--json | --text | --events] [--out <file.ndjson>]\n` +
+        `   or: ${CLI_COMMAND_NAME} session --prod [<sessionId>] --slug <slug> --message "…" [--dry-run] [--as-of <instant>]\n`
     );
     return 2;
   }

package/src/internal/cli-cursor.ts

@@ -17,6 +17,7 @@ import {
   revokeMintedUserApiKey,
 } from "./cursor/backend-client.js";
 import {
+  type ApiKeySource,
   clearStoredCredentials,
   credentialsFilePath,
   cursorBackendUrl,
@@ -255,7 +256,7 @@ function formatIdentity(identity: CursorIdentity): string {
   return name === "" ? `${email}${team}` : `${name} <${email}>${team}`;
 }
 
-function describeSource(source: "option" | "env" | "file" | "login"): string {
+function describeSource(source: ApiKeySource): string {
   switch (source) {
     case "option":
       return "explicit --api-key / serve({ apiKey })";
@@ -263,6 +264,8 @@ function describeSource(source: "option" | "env" | "file" | "login"): string {
       return "CURSOR_API_KEY environment variable";
     case "file":
       return "CURSOR_API_KEY_FILE (task bind)";
+    case "service-account":
+      return "CURSOR_SERVICE_ACCOUNT_KEY environment variable";
     case "login":
       return `stored login (${credentialsFilePath()})`;
   }