@cursor/july 0.1.94 → 0.1.96

package/src/internal/hosted-delivery.ts

@@ -10,6 +10,14 @@ import type {
   ChannelHandlerArgs,
   SendMessageOptions,
 } from "../types.js";
+import {
+  createDeferredChannelSession,
+  DeferredChannelSessionError,
+} from "./deferred-channel-session.js";
+import {
+  HostedAdmissionLocalSendError,
+  runDuringHostedAdmission,
+} from "./hosted-admission-context.js";
 import {
   HOSTED_ADMISSION_PATH,
   HOSTED_DELIVERY_HEADER,
@@ -19,6 +27,7 @@ import {
   parseHostedAdmission,
   parseHostedExecution,
 } from "./hosted-delivery-protocol.js";
+import { recordHostedManagedAutomation } from "./hosted-managed-automation.js";
 import { errorResponse, readJsonObject } from "./http-channel.js";
 import type { Router } from "./router.js";
 
@@ -45,19 +54,66 @@ type ExecutionReply = {
   body: Record<string, unknown>;
 };
 
-class HostedSendAdmitted extends Error {
-  constructor(
-    readonly prompt: string,
-    readonly options: SendMessageOptions
-  ) {
-    super("hosted channel admitted a send");
+/**
+ * A second `send()` in one delivery is a deterministic authored bug — the
+ * wire protocol carries exactly one pending send per delivery — so it must
+ * fail the delivery exactly once. It surfaces as a 422 because the control
+ * plane retries 5xx admissions (fresh pod, side effects re-run, identical
+ * failure, up to the Temporal attempt cap); a non-5xx/408/429 status makes
+ * it reject the delivery non-retryably instead.
+ */
+class HostedSendLimitExceeded extends Error {
+  constructor() {
+    super(
+      "The hosted delivery protocol carries exactly one pending send per " +
+        "delivery, and this delivery already captured one. Combine both " +
+        "messages into a single send(), or split the work across deliveries."
+    );
   }
 }
 
+// Authored/task-derived text stays bounded on this internal response path
+// (and is never persisted to Temporal history by the control plane).
+const MAX_ERROR_MESSAGE_LENGTH = 1024;
+
+function boundedMessage(text: string): string {
+  return text.length > MAX_ERROR_MESSAGE_LENGTH
+    ? `${text.slice(0, MAX_ERROR_MESSAGE_LENGTH)}…`
+    : text;
+}
+
+/**
+ * Classify deterministic authored protocol violations as non-retryable 422
+ * admissions. Anything else returns `undefined` so callers fall through to
+ * the existing (retryable or rethrow) handling.
+ */
+function nonRetryableRejection(error: unknown): AdmissionDispatch | undefined {
+  const code =
+    error instanceof HostedSendLimitExceeded
+      ? "hosted_send_limit_exceeded"
+      : error instanceof DeferredChannelSessionError
+        ? "hosted_deferred_session_unusable"
+        : error instanceof HostedAdmissionLocalSendError
+          ? "hosted_local_send_rejected"
+          : undefined;
+  if (code === undefined) {
+    return undefined;
+  }
+  return {
+    response: errorResponse(
+      422,
+      code,
+      boundedMessage((error as Error).message)
+    ),
+  };
+}
+
 /**
  * Run authored admission without creating a framework session. V1 GitHub
- * `task` callbacks execute as sessionless work; `send` is captured and
- * resumed only after the control plane allocates `ses_…`.
+ * `task` callbacks execute as sessionless work; the first `send` is captured
+ * and executed only after the control plane allocates `ses_…`. Capturing
+ * does not terminate the caller — `send` returns an inert deferred handle so
+ * a task body runs to completion before the admission response is computed.
  */
 export async function dispatchHostedAdmission(
   input: DispatchInput
@@ -71,24 +127,28 @@ export async function dispatchHostedAdmission(
       ),
     };
   }
+  // The admission window marker follows the async graph into task bodies so
+  // the engine can refuse local sends that would bypass the capture stub.
+  return runDuringHostedAdmission(() => runAdmission(input, github));
+}
 
+async function runAdmission(
+  input: DispatchInput,
+  github: NonNullable<ReturnType<typeof getGitHubChannelOptions>>
+): Promise<AdmissionDispatch> {
   const background: Promise<unknown>[] = [];
-  let deferredSend: HostedSendAdmitted | undefined;
+  let captured: { message: string; options: SendMessageOptions } | undefined;
   const args = withPropagatingGitHubBackgroundErrors({
     ...input.args,
     send: async (message, options = {}) => {
-      throw new HostedSendAdmitted(message, options);
+      if (captured !== undefined) {
+        throw new HostedSendLimitExceeded();
+      }
+      captured = { message, options };
+      return createDeferredChannelSession();
     },
     waitUntil: (promise) => {
-      background.push(
-        promise.catch((error: unknown) => {
-          if (error instanceof HostedSendAdmitted) {
-            deferredSend = error;
-            return;
-          }
-          throw error;
-        })
-      );
+      background.push(promise);
     },
   });
   let dispatched: Response;
@@ -101,20 +161,9 @@ export async function dispatchHostedAdmission(
       args,
     });
   } catch (error) {
-    if (error instanceof HostedSendAdmitted) {
-      return {
-        response: Response.json({
-          ok: true,
-          v: HOSTED_DELIVERY_PROTOCOL_VERSION,
-          outcome: "send",
-        }),
-        pendingSend: {
-          channelId: input.delivery.channelId,
-          message: error.prompt,
-          options: error.options,
-          mailboxContinuationKey: input.delivery.mailboxContinuationKey,
-        },
-      };
+    const rejected = nonRetryableRejection(error);
+    if (rejected !== undefined) {
+      return rejected;
     }
     throw error;
   }
@@ -129,15 +178,20 @@ export async function dispatchHostedAdmission(
 
   try {
     await Promise.all(background);
-  } catch {
+  } catch (error) {
+    const rejected = nonRetryableRejection(error);
+    if (rejected !== undefined) {
+      return rejected;
+    }
     return {
-      response: Response.json(
-        { ok: false, error: "background_dispatch_failed" },
-        { status: 503 }
+      response: errorResponse(
+        503,
+        "background_dispatch_failed",
+        boundedMessage(error instanceof Error ? error.message : String(error))
       ),
     };
   }
-  if (deferredSend !== undefined) {
+  if (captured !== undefined) {
     return {
       response: Response.json({
         ok: true,
@@ -146,8 +200,8 @@ export async function dispatchHostedAdmission(
       }),
       pendingSend: {
         channelId: input.delivery.channelId,
-        message: deferredSend.prompt,
-        options: deferredSend.options,
+        message: captured.message,
+        options: captured.options,
         mailboxContinuationKey: input.delivery.mailboxContinuationKey,
       },
     };
@@ -191,6 +245,13 @@ export function registerHostedDeliveryRoute(input: {
     channelId: string,
     sessionPublicId?: string
   ): ChannelHandlerArgs;
+  /**
+   * Await the session's durable mirror (dispatch chain + storage queue)
+   * before the execution reply: the control plane may park the pod the
+   * moment the reply lands, and a shed session-record flush would strand
+   * the conversation on the next wake.
+   */
+  drainSessionDurability?(sessionId: string): Promise<void>;
 }): void {
   const pending = new Map<
     string,
@@ -241,6 +302,7 @@ export function registerHostedDeliveryRoute(input: {
           )
         );
       }
+      recordHostedManagedAutomation(delivery);
       const channel = input.channels.find(
         (candidate) => candidate.id === delivery.channelId
       );
@@ -332,6 +394,9 @@ export function registerHostedDeliveryRoute(input: {
           },
         });
         const outcome = await session.waitForCompletion();
+        // Failed turns drain too: their record/continuation updates must
+        // survive the park just like a finished turn's.
+        await input.drainSessionDurability?.(session.id);
         if (outcome.status !== "finished") {
           return {
             status: 503,

package/src/internal/hosted-managed-automation.ts

@@ -0,0 +1,72 @@
+/**
+ * Managed-automation envelope slices by provider delivery id (plan 0002
+ * G2), recorded at hosted admission so channel code running the delivery's
+ * task (or session turn) can attach the customer's MCP servers through the
+ * control-plane relay. In-memory and TTL-bounded like the hosted pending-
+ * send table: the envelope slice carries names only (never credentials)
+ * and evaporates with the process.
+ *
+ * A leaf module (protocol type import only) so product channels can read
+ * it without pulling the hosted-delivery route — and its session-engine
+ * dependency graph — into their bundles.
+ *
+ * INTERNAL: first-party multi-tenant deployment plumbing. Deliberately
+ * excluded from the published `@cursor/july` npm package (see the `files`
+ * whitelist); consumed by internal deployments via relative source imports.
+ */
+
+import type { HostedAdmissionManagedAutomation } from "./hosted-delivery-protocol.js";
+
+const managedAutomationByDelivery = new Map<
+  string,
+  { managedAutomation: HostedAdmissionManagedAutomation; expiresAt: number }
+>();
+/** Long enough to outlive a slow review run kicked off by the delivery. */
+const MANAGED_AUTOMATION_TTL_MS = 60 * 60_000;
+const MANAGED_AUTOMATION_MAX_ENTRIES = 10_000;
+
+export function recordHostedManagedAutomation(delivery: {
+  deliveryId: string;
+  managedAutomation?: HostedAdmissionManagedAutomation;
+}): void {
+  if (delivery.managedAutomation === undefined) {
+    return;
+  }
+  const now = Date.now();
+  for (const [key, entry] of managedAutomationByDelivery) {
+    if (entry.expiresAt <= now) {
+      managedAutomationByDelivery.delete(key);
+    }
+  }
+  if (managedAutomationByDelivery.size >= MANAGED_AUTOMATION_MAX_ENTRIES) {
+    managedAutomationByDelivery.clear();
+  }
+  managedAutomationByDelivery.set(delivery.deliveryId, {
+    managedAutomation: delivery.managedAutomation,
+    expiresAt: now + MANAGED_AUTOMATION_TTL_MS,
+  });
+}
+
+/**
+ * The managed automation the control plane attributed to a hosted delivery,
+ * when the envelope carried one. Undefined for non-managed deliveries,
+ * expired entries, and non-hosted (webhook/stream) dispatch paths.
+ */
+export function getHostedManagedAutomation(
+  deliveryId: string
+): HostedAdmissionManagedAutomation | undefined {
+  const entry = managedAutomationByDelivery.get(deliveryId);
+  if (entry === undefined) {
+    return undefined;
+  }
+  if (entry.expiresAt <= Date.now()) {
+    managedAutomationByDelivery.delete(deliveryId);
+    return undefined;
+  }
+  return entry.managedAutomation;
+}
+
+/** Drop recorded managed-automation slices (tests only). */
+export function resetHostedManagedAutomationForTest(): void {
+  managedAutomationByDelivery.clear();
+}

package/src/internal/init-project.ts

@@ -74,6 +74,7 @@ type TemplateEntry = {
 
 const TEMPLATES: Readonly<Record<TemplateName, TemplateEntry>> = {
   "agentic-owners": { dir: "agentic-owners" },
+  "code-wiki": { dir: "code-wiki" },
   demo: { dir: "demo" },
   "pr-autofixer": { dir: "pr-autofixer" },
   "security-help": { dir: "security-help" },
@@ -709,6 +710,7 @@ export function printInitGuide(): void {
 Scaffold a project, then open the playground:
   npx ${PACKAGE_NAME} init ./my-agent   # installs deps + links agent-sdk onto PATH
   npx ${PACKAGE_NAME} init ./my-demo --template demo              # record a PR walkthrough
+  npx ${PACKAGE_NAME} init ./code-wiki --template code-wiki       # keep wiki pages current after merge
   npx ${PACKAGE_NAME} init ./my-reviewer --template security-reviewer   # review PRs for security bugs
   npx ${PACKAGE_NAME} init ./security-help --template security-help   # answer security questions in Slack
   npx ${PACKAGE_NAME} init ./my-triage --template triage-linear   # comment on Linear issues

package/src/internal/install-cursor-skills.ts

@@ -31,9 +31,6 @@ import { CLI_COMMAND_NAME, packageRootDir } from "./distribution.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { stdoutPalette } from "./terminal-style.js";
 
-/** Monorepo-only skill; excluded from the published package. */
-const SKIP_SKILL_DIRS = new Set(["operate"]);
-
 /** Category folder under ~/.cursor/skills (Cursor discovers nested skills). */
 export const CURSOR_SKILLS_NAMESPACE = "agentsdk";
 
@@ -122,7 +119,7 @@ export async function listShippedPackageSkills(
 
   const skills: PackageSkill[] = [];
   for (const entry of entries) {
-    if (!entry.isDirectory() || SKIP_SKILL_DIRS.has(entry.name)) {
+    if (!entry.isDirectory()) {
       continue;
     }
     const sourceDir = join(skillsRoot, entry.name);

package/src/internal/managed-delivery.ts

@@ -0,0 +1,125 @@
+/**
+ * Envelope-carried installation config for managed-product deliveries
+ * (plan 0002 Stack H1; envelope shape from Stack B1).
+ *
+ * On the v2 architecture a managed product (security-reviewer, …) is many
+ * single-tenant deployments: the pre-signal trigger gate matches the
+ * customer's automation trigger before a workflow starts and stamps the
+ * matched automation uuid + an opaque installation-config reference on the
+ * attributed session envelope. The delivery activity forwards the matched
+ * installation-config document to the fork **inside the webhook payload it
+ * POSTs to the channel**, under {@link MANAGED_DELIVERY_PAYLOAD_KEY} — the
+ * same embed-in-payload pattern the legacy deployment event stream used
+ * for its source marker.
+ *
+ * This module is the one contract both sides share: the control-plane
+ * delivery path embeds with {@link withManagedDeliveryConfig}; the agent's
+ * channels detect and read with {@link parseManagedDeliveryConfig}. The
+ * document mirrors the sync layer's `ManagedAutomationConfigDoc` **policy**
+ * fields that "ride the delivery envelope to the fork" (posting mode,
+ * managed config, trigger snapshots for the channel's staleness guard);
+ * readers ignore unknown fields so a newer sync can add material without
+ * breaking older forks. The automation's MCP server refs deliberately do
+ * NOT ride here: they travel on the hosted-admission envelope's
+ * `managedAutomation` slice (plan 0002 G2, `hosted-delivery-protocol.ts` /
+ * `hosted-managed-automation.ts`) so one mechanism owns MCP attach.
+ *
+ * INTERNAL: first-party host plumbing shared by agents in `factory/*`,
+ * consumed via relative source imports. Deliberately excluded from the
+ * published `@cursor/july` npm package (see the `files` whitelist).
+ */
+
+/**
+ * Key inside the delivered webhook payload under which the delivery
+ * activity embeds the matched installation config. Chosen to never
+ * collide with a provider webhook field (GitHub and Origin payloads have
+ * no `cursor*` keys).
+ */
+export const MANAGED_DELIVERY_PAYLOAD_KEY = "cursorManagedDelivery" as const;
+
+/**
+ * The matched installation-config document as it rides the delivery to
+ * the fork. Required: the matched automation uuid (B1 attribution).
+ * Everything else is optional; absent fields keep the channel's default
+ * posture (post, all modules enabled, no staleness guard).
+ */
+export interface ManagedDeliveryInstallationConfig {
+  /** Source managed automation uuid the pre-signal gate matched. */
+  matchedAutomationUuid: string;
+  /** Opaque `<installationId>@<resourceVersion>` config reference. */
+  installationConfigRef?: string;
+  managedType?: string;
+  name?: string;
+  /**
+   * Whether product output (PR comments, …) posts for this installation,
+   * or the run stays check/shadow-only. Channels post only on `"post"`
+   * (or when the field is absent) — any other value fails closed to
+   * shadow, so a newer mode name never posts by accident.
+   */
+  postingMode?: string;
+  managedConfig?: Record<string, unknown>;
+  /**
+   * The automation's git triggers as `GitTrigger.toJson()` snapshots.
+   * The channel re-checks the delivery against them (staleness guard:
+   * the config may have changed between admission and delivery).
+   */
+  triggerSnapshots?: unknown[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/**
+ * Read the embedded installation config out of a delivered webhook
+ * payload. Returns undefined for payloads without the key (legacy
+ * deliveries, host relay, fixtures) and for documents missing the
+ * required matched automation uuid — the channel then runs its legacy
+ * path unchanged. Malformed optional fields are dropped, not fatal.
+ */
+export function parseManagedDeliveryConfig(
+  payload: unknown
+): ManagedDeliveryInstallationConfig | undefined {
+  if (!isRecord(payload)) {
+    return undefined;
+  }
+  const doc = payload[MANAGED_DELIVERY_PAYLOAD_KEY];
+  if (!isRecord(doc)) {
+    return undefined;
+  }
+  const matchedAutomationUuid = nonEmptyString(doc.matchedAutomationUuid);
+  if (matchedAutomationUuid === undefined) {
+    return undefined;
+  }
+  return {
+    matchedAutomationUuid,
+    installationConfigRef: nonEmptyString(doc.installationConfigRef),
+    managedType: nonEmptyString(doc.managedType),
+    name: nonEmptyString(doc.name),
+    postingMode: nonEmptyString(doc.postingMode),
+    managedConfig: isRecord(doc.managedConfig) ? doc.managedConfig : undefined,
+    triggerSnapshots: Array.isArray(doc.triggerSnapshots)
+      ? doc.triggerSnapshots
+      : undefined,
+  };
+}
+
+/**
+ * Embed one matched installation config into the webhook payload the
+ * delivery activity POSTs to the channel. Pure; used by the control-plane
+ * delivery path and by channel tests building fixture envelopes.
+ */
+export function withManagedDeliveryConfig(
+  payload: Record<string, unknown>,
+  config: ManagedDeliveryInstallationConfig
+): Record<string, unknown> {
+  return { ...payload, [MANAGED_DELIVERY_PAYLOAD_KEY]: config };
+}

package/src/internal/review-comments.ts

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import type { HostGitHubClient } from "../types.js";
+import { parsePrUrl } from "./scm/pr-url.js";
 
 export type ReviewCommentPublisher = "local_gh" | "host_github" | "host_origin";
 
@@ -198,8 +199,15 @@ export type ReviewThreadResolverImplementation = {
 export function resolveScmReviewTarget(
   prUrl: string
 ): ScmReviewTarget | undefined {
-  const parsed = parseReviewPrUrl(prUrl);
-  return parsed.kind === "valid" ? parsed.value : undefined;
+  const parsed = parsePrUrl(prUrl);
+  if (parsed === undefined) {
+    return undefined;
+  }
+  return {
+    provider: parsed.provider,
+    repo: `${parsed.owner}/${parsed.repo}`,
+    prNumber: parsed.number,
+  };
 }
 
 /**
@@ -1243,117 +1251,6 @@ function skippedResolve(detail: string): ResolveReviewThreadsResult {
   };
 }
 
-const ORIGIN_PR_PAGE_HOST_PATTERN = /^origin(-[a-z0-9]+)?\.cursor\.com$/i;
-
-/**
- * Provider-neutral PR URL parse. GitHub.com plus the Origin page shapes
- * `parsePrTarget` in security-review-lib accepts. Duplicated here so
- * agent-serve does not import that package.
- */
-function parseReviewPrUrl(
-  prUrl: string
-):
-  | { kind: "valid"; value: ScmReviewTarget }
-  | { kind: "invalid"; detail: string } {
-  let url: URL;
-  try {
-    url = new URL(prUrl);
-  } catch (error) {
-    return {
-      kind: "invalid",
-      detail: `unparseable PR URL: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-
-  const parts = url.pathname.split("/").filter(Boolean);
-  const hostname = url.hostname;
-
-  if (hostname === "github.com" && parts.length >= 4 && parts[2] === "pull") {
-    const prNumber = Number(parts[3]);
-    if (Number.isInteger(prNumber) && prNumber > 0) {
-      return {
-        kind: "valid",
-        value: {
-          provider: "github",
-          repo: `${parts[0]}/${parts[1]}`,
-          prNumber,
-        },
-      };
-    }
-  }
-
-  if (
-    ORIGIN_PR_PAGE_HOST_PATTERN.test(hostname) &&
-    parts.length >= 4 &&
-    parts[2] === "github"
-  ) {
-    const prNumber = Number(parts[3]);
-    if (Number.isInteger(prNumber) && prNumber > 0) {
-      return {
-        kind: "valid",
-        value: {
-          provider: "origin",
-          repo: `${parts[0]}/${parts[1]}`,
-          prNumber,
-        },
-      };
-    }
-  }
-
-  if (
-    /^(www\.)?cursor\.com$/i.test(hostname) &&
-    parts[0] === "codebase" &&
-    parts.length >= 5 &&
-    parts[3] === "pull"
-  ) {
-    const prNumber = Number(parts[4]);
-    if (Number.isInteger(prNumber) && prNumber > 0) {
-      return {
-        kind: "valid",
-        value: {
-          provider: "origin",
-          repo: `${parts[1]}/${parts[2]}`,
-          prNumber,
-        },
-      };
-    }
-  }
-
-  if (hostname === "review.cursor.com" && parts[0] === "pr") {
-    if (parts.length >= 5 && parts[3] === "github") {
-      const prNumber = Number(parts[4]);
-      if (Number.isInteger(prNumber) && prNumber > 0) {
-        return {
-          kind: "valid",
-          value: {
-            provider: "origin",
-            repo: `${parts[1]}/${parts[2]}`,
-            prNumber,
-          },
-        };
-      }
-    }
-    if (parts.length >= 4) {
-      const prNumber = Number(parts[3]);
-      if (Number.isInteger(prNumber) && prNumber > 0) {
-        return {
-          kind: "valid",
-          value: {
-            provider: "origin",
-            repo: `${parts[1]}/${parts[2]}`,
-            prNumber,
-          },
-        };
-      }
-    }
-  }
-
-  return {
-    kind: "invalid",
-    detail: "unparseable PR URL: not a GitHub or Origin pull request",
-  };
-}
-
 function parseGithubPrUrl(
   prUrl: string
 ):

package/src/internal/runtime-dispatch-runner.ts

@@ -13,6 +13,7 @@ import type {
   AgentRunner,
   PrewarmOutcome,
   RunnerPrewarmRequest,
+  SteerAckOutcome,
 } from "./sdk-runner.js";
 
 export interface RuntimeDispatchingRunnerOptions {
@@ -45,6 +46,15 @@ export class RuntimeDispatchingRunner implements AgentRunner {
     return this.options.sdkRunner.runTurn(request);
   }
 
+  async steer(request: {
+    sessionId: string;
+    text: string;
+  }): Promise<SteerAckOutcome> {
+    return (
+      (await this.options.sdkRunner.steer?.(request)) ?? "revert_to_followup"
+    );
+  }
+
   async prewarm(request: RunnerPrewarmRequest): Promise<PrewarmOutcome> {
     // Prewarming is a local-harness concern; the engine only calls it for
     // local-runtime agents.