@cursor/july 0.1.107 → 0.1.108

package/src/channels.ts

@@ -64,9 +64,11 @@ export {
 } from "./channels/checks.js";
 
 import { Buffer } from "node:buffer";
-import { timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { brandDefinition } from "./internal/brand.js";
 import { normalizeIdentity } from "./internal/continuation-identity.js";
+import { attachCatchAdmission } from "./internal/hosted-catch.js";
+import { attachHttpControlPlaneAdmission } from "./internal/http-control-plane-session.js";
 import { isLoopbackAddress, isLoopbackHostname } from "./internal/net.js";
 import type {
   AuthContext,
@@ -117,7 +119,16 @@ export type {
 export function defineChannel<TState = JsonValue>(
   config: ChannelConfig<TState>
 ): ChannelDefinition<TState> {
-  return brandDefinition("channel", config);
+  const definition = brandDefinition("channel", config);
+  if (config.routes !== undefined && config.routes.length > 0) {
+    // Hosted: the control plane catches declared routes and replays them
+    // here. Provider packs attach their own admission afterwards.
+    attachCatchAdmission(
+      definition as ChannelDefinition<unknown>,
+      config.routes
+    );
+  }
+  return definition;
 }
 
 /**
@@ -127,13 +138,15 @@ export function defineChannel<TState = JsonValue>(
 export function httpChannel(
   config: HttpChannelConfig = {}
 ): HttpChannelDefinition {
-  if (config.continuation !== undefined) {
-    return brandDefinition("http-channel", {
-      ...config,
-      continuation: normalizeIdentity(config.continuation, "http"),
-    });
-  }
-  return brandDefinition("http-channel", config);
+  const definition =
+    config.continuation !== undefined
+      ? brandDefinition("http-channel", {
+          ...config,
+          continuation: normalizeIdentity(config.continuation, "http"),
+        })
+      : brandDefinition("http-channel", config);
+  attachHttpControlPlaneAdmission(definition);
+  return definition;
 }
 
 // ============================================================================
@@ -432,7 +445,13 @@ export function publicEndpoint(): AuthPolicy {
     principalId: "anonymous",
     principalType: "user",
   });
-  return Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true as const });
+  // On the v2 control plane this also makes the channel's routes catchable
+  // with handler-side verification (the v1 alias posture): the CP admits
+  // every request on a declared route and the handler rejects bad ones.
+  return markCatchAuth(
+    Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true as const }),
+    { kind: "public" }
+  );
 }
 
 /** True when a policy was created by {@link publicEndpoint}. */
@@ -443,3 +462,131 @@ export function isPublicEndpointPolicy(policy: AuthPolicy): boolean {
     ] === true
   );
 }
+
+const CATCH_AUTH_MARKER = Symbol.for("agent-serve.catch-auth");
+
+/**
+ * What `deploy` extracts from a {@link sharedSecretAuth} /
+ * {@link hmacSignatureAuth} policy into the manifest: the control plane runs
+ * the same check with the deployment secret of the same name before any
+ * compute starts. `secret` is a name, never a value.
+ */
+export type CatchAuthDeclaration =
+  | { kind: "header"; header: string; secret: string }
+  | { kind: "hmac-sha256"; header: string; secret: string; prefix?: string }
+  /** `publicEndpoint()`: the handler verifies; the control plane only rate limits. */
+  | { kind: "public" };
+
+function markCatchAuth(
+  policy: AuthPolicy,
+  declaration: CatchAuthDeclaration
+): AuthPolicy {
+  return Object.assign(policy, { [CATCH_AUTH_MARKER]: declaration });
+}
+
+/** The catch declaration a policy carries, if it is a catch-capable policy. */
+export function catchAuthDeclaration(
+  policy: AuthPolicy
+): CatchAuthDeclaration | undefined {
+  const declaration = (policy as { [CATCH_AUTH_MARKER]?: unknown })[
+    CATCH_AUTH_MARKER
+  ];
+  return typeof declaration === "object" && declaration !== null
+    ? (declaration as CatchAuthDeclaration)
+    : undefined;
+}
+
+function presentedHeaderSecret(headerName: string, value: string): string {
+  if (
+    headerName === "authorization" &&
+    value.toLowerCase().startsWith("bearer ")
+  ) {
+    return value.slice("bearer ".length).trim();
+  }
+  return value.trim();
+}
+
+/**
+ * Admit requests whose `header` equals the secret named `secret` (an
+ * `Authorization: Bearer <secret>` header also matches). Locally the value
+ * is `process.env[secret]`; hosted, the deployment secret of that name. On
+ * Cursor hosting this ALSO declares the channel's routes reachable through
+ * the control-plane catch API, which runs the same comparison before any
+ * compute exists. An unset secret admits nothing.
+ */
+export function sharedSecretAuth(options: {
+  header: string;
+  secret: string;
+}): AuthPolicy {
+  const header = options.header.toLowerCase();
+  const policy: AuthPolicy = (request) => {
+    const expected = process.env[options.secret];
+    const presented = request.headers.get(header);
+    if (
+      expected === undefined ||
+      expected.length === 0 ||
+      presented === null ||
+      !constantTimeEquals(presentedHeaderSecret(header, presented), expected)
+    ) {
+      return null;
+    }
+    return {
+      authenticator: "shared-secret",
+      principalId: "webhook",
+      principalType: "service",
+    };
+  };
+  return markCatchAuth(policy, {
+    kind: "header",
+    header,
+    secret: options.secret,
+  });
+}
+
+/**
+ * Admit requests whose `header` carries the hex HMAC-SHA256 of the raw body
+ * under the secret named `secret` (optionally behind a literal `prefix`
+ * such as `sha256=`). Same local / hosted / catch semantics as
+ * {@link sharedSecretAuth}.
+ */
+export function hmacSignatureAuth(options: {
+  header: string;
+  secret: string;
+  prefix?: string;
+}): AuthPolicy {
+  const header = options.header.toLowerCase();
+  const prefix = options.prefix ?? "";
+  const policy: AuthPolicy = async (request) => {
+    const secret = process.env[options.secret];
+    const presented = request.headers.get(header)?.trim();
+    if (
+      secret === undefined ||
+      secret.length === 0 ||
+      presented === undefined ||
+      !presented.startsWith(prefix)
+    ) {
+      return null;
+    }
+    const body = Buffer.from(await request.clone().arrayBuffer());
+    const expected = createHmac("sha256", secret).update(body).digest("hex");
+    if (
+      !constantTimeEquals(
+        presented.slice(prefix.length).toLowerCase(),
+        expected
+      )
+    ) {
+      return null;
+    }
+    return {
+      authenticator: "hmac-signature",
+      principalId: "webhook",
+      principalType: "service",
+    };
+  };
+  return markCatchAuth(policy, {
+    kind: "hmac-sha256",
+    header,
+    secret: options.secret,
+    prefix: options.prefix,
+  });
+}

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/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

@@ -23,6 +23,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 +54,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 +191,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 +603,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 +721,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 +1813,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 +1841,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 +1956,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;
   }