@cursor/july 0.1.95 → 0.1.97

package/src/internal/hosted-execution-diag.ts

@@ -0,0 +1,207 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { HOSTED_EXECUTION_DIAG_FILENAME } from "./hosted-delivery-protocol.js";
+
+export const HOSTED_EXECUTION_DIAG_VERSION = 1;
+/** Cap so a runaway message cannot fill the guest disk or the host log. */
+export const HOSTED_EXECUTION_DIAG_MAX_BYTES = 4096;
+
+/**
+ * Correlate the on-disk record with the execution that produced it. One pod
+ * serves many deliveries of a continuation session, and the file lives at a
+ * single fixed path, so without this the host can read a *previous*
+ * delivery's terminal record whenever July never reaches its own write —
+ * the 9-minute host POST timeout, a 409 on an expired admission token, or a
+ * replayed token that short-circuits on the memoized reply.
+ *
+ * Derived from the admission token (which both sides already hold) rather
+ * than carried on the wire. The digest is one-way, so the token itself never
+ * reaches the guest disk or the host logs.
+ */
+export function hostedExecutionDiagId(admissionToken: string): string {
+  return createHash("sha256").update(admissionToken).digest("hex").slice(0, 16);
+}
+
+export type HostedExecutionDiagAbortReason =
+  | "signal_abort"
+  | "runner_cancelled"
+  | "runner_error"
+  | "execute_throw";
+
+/**
+ * Bounded guest-side record of one hosted-execution attempt. No prompt,
+ * tool content, or API key — the host copies known keys onto the Temporal
+ * activity span for Datadog.
+ */
+export type HostedExecutionDiag = {
+  v: typeof HOSTED_EXECUTION_DIAG_VERSION;
+  /** {@link hostedExecutionDiagId} of the execution that wrote this record. */
+  executionId: string;
+  writtenAt: string;
+  sessionPublicId: string;
+  sessionId: string;
+  /** Terminal {@link TurnOutcome} status, or `running` before the turn ends. */
+  turnStatus: string;
+  durationMs: number;
+  message?: string;
+  signalAborted?: boolean;
+  requestId?: string;
+  abortReason?: HostedExecutionDiagAbortReason;
+};
+
+/** Written before the turn starts so a stalled execution still has a record. */
+export const HOSTED_EXECUTION_DIAG_RUNNING_STATUS = "running";
+
+const DIAG_KEYS = new Set([
+  "v",
+  "executionId",
+  "writtenAt",
+  "sessionPublicId",
+  "sessionId",
+  "turnStatus",
+  "durationMs",
+  "message",
+  "signalAborted",
+  "requestId",
+  "abortReason",
+]);
+
+const ABORT_REASONS = new Set<HostedExecutionDiagAbortReason>([
+  "signal_abort",
+  "runner_cancelled",
+  "runner_error",
+  "execute_throw",
+]);
+
+function boundedOptionalString(
+  value: unknown,
+  max: number
+): string | undefined {
+  return typeof value === "string" && value.length > 0
+    ? value.length > max
+      ? `${value.slice(0, max)}…`
+      : value
+    : undefined;
+}
+
+export function hostedExecutionDiagPath(stateRoot: string): string {
+  return join(stateRoot, HOSTED_EXECUTION_DIAG_FILENAME);
+}
+
+export function abortReasonFromTurnStatus(
+  status: string,
+  message: string | undefined
+): HostedExecutionDiagAbortReason | undefined {
+  if (status === "finished") {
+    return undefined;
+  }
+  if (status === "cancelled") {
+    return message !== undefined && /abort/i.test(message)
+      ? "signal_abort"
+      : "runner_cancelled";
+  }
+  return "runner_error";
+}
+
+export function parseHostedExecutionDiag(
+  raw: string
+): HostedExecutionDiag | undefined {
+  if (raw.length === 0 || raw.length > HOSTED_EXECUTION_DIAG_MAX_BYTES) {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return undefined;
+  }
+  const body = parsed as Record<string, unknown>;
+  if (Object.keys(body).some((key) => !DIAG_KEYS.has(key))) {
+    return undefined;
+  }
+  if (
+    body.v !== HOSTED_EXECUTION_DIAG_VERSION ||
+    typeof body.executionId !== "string" ||
+    body.executionId.length === 0 ||
+    body.executionId.length > 64 ||
+    typeof body.writtenAt !== "string" ||
+    body.writtenAt.length === 0 ||
+    body.writtenAt.length > 64 ||
+    typeof body.sessionPublicId !== "string" ||
+    body.sessionPublicId.length === 0 ||
+    body.sessionPublicId.length > 128 ||
+    typeof body.sessionId !== "string" ||
+    body.sessionId.length > 128 ||
+    typeof body.turnStatus !== "string" ||
+    body.turnStatus.length === 0 ||
+    body.turnStatus.length > 64 ||
+    typeof body.durationMs !== "number" ||
+    !Number.isFinite(body.durationMs) ||
+    body.durationMs < 0
+  ) {
+    return undefined;
+  }
+  const message = boundedOptionalString(body.message, 1024);
+  const requestId = boundedOptionalString(body.requestId, 128);
+  const abortReason =
+    body.abortReason === undefined
+      ? undefined
+      : typeof body.abortReason === "string" &&
+          ABORT_REASONS.has(body.abortReason as HostedExecutionDiagAbortReason)
+        ? (body.abortReason as HostedExecutionDiagAbortReason)
+        : undefined;
+  if (body.abortReason !== undefined && abortReason === undefined) {
+    return undefined;
+  }
+  if (
+    body.signalAborted !== undefined &&
+    typeof body.signalAborted !== "boolean"
+  ) {
+    return undefined;
+  }
+  return {
+    v: HOSTED_EXECUTION_DIAG_VERSION,
+    executionId: body.executionId,
+    writtenAt: body.writtenAt,
+    sessionPublicId: body.sessionPublicId,
+    sessionId: body.sessionId,
+    turnStatus: body.turnStatus,
+    durationMs: body.durationMs,
+    ...(message === undefined ? {} : { message }),
+    ...(body.signalAborted === true ? { signalAborted: true } : {}),
+    ...(requestId === undefined ? {} : { requestId }),
+    ...(abortReason === undefined ? {} : { abortReason }),
+  };
+}
+
+/**
+ * Overwrite the per-execution diag file. Soft-fail: a write error must not
+ * change the hosted-execution HTTP reply.
+ */
+export async function writeHostedExecutionDiag(
+  stateRoot: string,
+  diag: HostedExecutionDiag
+): Promise<void> {
+  const path = hostedExecutionDiagPath(stateRoot);
+  const tmp = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+  try {
+    await mkdir(stateRoot, { recursive: true });
+    const serialized = JSON.stringify(diag);
+    const body =
+      serialized.length > HOSTED_EXECUTION_DIAG_MAX_BYTES
+        ? JSON.stringify({
+            ...diag,
+            message: boundedOptionalString(diag.message, 256),
+          })
+        : serialized;
+    await writeFile(tmp, body, "utf8");
+    await rename(tmp, path);
+  } catch {
+    await unlink(tmp).catch(() => undefined);
+  }
+}

package/src/internal/http-channel.ts

@@ -25,6 +25,8 @@ import type { ServerRoute } from "./router.js";
 import {
   ApprovalInterruptedError,
   ApprovalNotFoundError,
+  AuthInterruptedError,
+  AuthNotFoundError,
   HTTP_CHANNEL_ID,
   SessionAuthError,
   type SessionEngine,
@@ -454,6 +456,101 @@ export function buildHttpChannelRoutes(args: {
     },
   };
 
+  const listAuths: ServerRoute = {
+    method: "GET",
+    pattern: `${base}/v1/session/:sessionId/auths`,
+    auth,
+    handler: async (_request, ctx) => {
+      const sessionId = ctx.params.sessionId ?? "";
+      const record = await engine.getOrRestoreSession(sessionId);
+      if (record === undefined) {
+        return errorResponse(
+          404,
+          "session_not_found",
+          `Unknown session ${sessionId}.`
+        );
+      }
+      const ownership = requireSessionOwner(record, ctx.auth, {
+        relax: relaxSessionReadAuth,
+        beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+        requestIp: ctx.requestIp,
+      });
+      if (ownership !== undefined) {
+        return ownership;
+      }
+      const pending = await engine.listPendingAuths(sessionId);
+      return jsonResponse({ ok: true, sessionId, pending });
+    },
+  };
+
+  const resolveAuth: ServerRoute = {
+    method: "POST",
+    pattern: `${base}/v1/session/:sessionId/auths/:callId`,
+    auth,
+    handler: async (request, ctx) => {
+      const sessionId = ctx.params.sessionId ?? "";
+      const callId = ctx.params.callId ?? "";
+      const record = await engine.getOrRestoreSession(sessionId);
+      if (record === undefined) {
+        return errorResponse(
+          404,
+          "session_not_found",
+          `Unknown session ${sessionId}.`
+        );
+      }
+      const bridgeSlackAuth =
+        relaxSessionApprovalAuth === true &&
+        record.auth?.authenticator === "slack" &&
+        (relaxSessionReadAuthBeyondLoopback === true ||
+          (typeof ctx.requestIp === "string" &&
+            isLoopbackAddress(ctx.requestIp)));
+      const ownership = requireSessionOwner(record, ctx.auth, {
+        relax: bridgeSlackAuth,
+        beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+        requestIp: ctx.requestIp,
+      });
+      if (ownership !== undefined) {
+        return ownership;
+      }
+      const body = await readJsonObject(request);
+      const decision = body?.decision;
+      if (decision !== "approve" && decision !== "deny") {
+        return errorResponse(
+          400,
+          "invalid_request",
+          'Expected a JSON body with `decision`: "approve" | "deny".'
+        );
+      }
+      try {
+        const pending = await engine.resolveAuth(
+          sessionId,
+          callId,
+          decision,
+          ctx.auth,
+          bridgeSlackAuth ? { asSessionOwner: true } : undefined
+        );
+        return jsonResponse({
+          ok: true,
+          sessionId,
+          callId,
+          decision,
+          connection: pending.connection,
+        });
+      } catch (error) {
+        if (error instanceof AuthNotFoundError) {
+          return errorResponse(404, "auth_not_found", error.message);
+        }
+        if (error instanceof AuthInterruptedError) {
+          return errorResponse(409, "auth_interrupted", error.message);
+        }
+        if (error instanceof SessionAuthError) {
+          return errorResponse(403, "forbidden", error.message);
+        }
+        throw error;
+      }
+    },
+  };
+
   return [
     createSession,
     followUp,
@@ -463,6 +560,8 @@ export function buildHttpChannelRoutes(args: {
     cost,
     listApprovals,
     resolveApproval,
+    listAuths,
+    resolveAuth,
   ];
 }
 

package/src/internal/init-project.ts

@@ -74,6 +74,8 @@ type TemplateEntry = {
 
 const TEMPLATES: Readonly<Record<TemplateName, TemplateEntry>> = {
   "agentic-owners": { dir: "agentic-owners" },
+  "agents-md": { dir: "agents-md" },
+  "code-wiki": { dir: "code-wiki" },
   demo: { dir: "demo" },
   "pr-autofixer": { dir: "pr-autofixer" },
   "security-help": { dir: "security-help" },
@@ -709,6 +711,8 @@ 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 ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
   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/logs-client.ts

@@ -114,6 +114,11 @@ export function sanitizeCustomerError(message: string): string {
 /**
  * One-line label for `agent-sdk deploy` polling (TTY spinner / non-TTY
  * transitions). Uses statusMessage → progress → raw status.
+ *
+ * Deliberately does NOT include `lastError`. The spinner redraws with
+ * `\r\x1b[2K`, which clears one physical row, so a reason long enough to
+ * soft-wrap would leave the earlier rows on screen. Callers print the
+ * reason once on the final line instead.
  */
 export function deployProgressLabel(detail: {
   status: string;

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/mcp-endpoint.ts

@@ -293,7 +293,11 @@ function buildConnectionBridgeMcpServer(
     if (reason !== undefined) {
       throw new Error(reason);
     }
-    const tools = await engine.host.mcp.listTools(connectionName);
+    const tools = await engine.runWithMcpPark(
+      sessionId ?? "",
+      "tools/list",
+      () => engine.host.mcp.listTools(connectionName)
+    );
     return {
       tools: tools.map((tool) => ({
         name: tool.name,
@@ -327,10 +331,15 @@ function buildConnectionBridgeMcpServer(
       return sdkResultToMcpResult(answer.result);
     }
     try {
-      const result = await engine.host.mcp.callTool(
-        connectionName,
+      const result = await engine.runWithMcpPark(
+        sessionId ?? "",
         request.params.name,
-        request.params.arguments ?? {}
+        () =>
+          engine.host.mcp.callTool(
+            connectionName,
+            request.params.name,
+            request.params.arguments ?? {}
+          )
       );
       return {
         // The host client already speaks MCP, so the content array is valid