@cursor/july 0.1.102 → 0.1.104

package/src/internal/testing/scm-continuation-fixtures.ts

@@ -0,0 +1,286 @@
+/**
+ * GitLab / Bitbucket continuation fixtures shared by the two continuation
+ * vocabulary copies — `internal/continuation-identity.ts` (July) and the
+ * control plane's `agentSdkConversationIdentity.ts` (server-shared). Both
+ * suites import this one module, so a payload shape or key format that only
+ * one copy understands fails CI on the other side.
+ *
+ * Pure data: no imports, so the server-shared suite can load it by relative
+ * path without pulling `@cursor/july` into the control plane.
+ */
+
+export interface ScmContinuationFixture {
+  name: string;
+  kind: "gitlab" | "bitbucket";
+  /** Conversation type the channel's `<kind>.<type>/v2` selector names. */
+  type: "gitlab-mr" | "bitbucket-pr";
+  /**
+   * Mailbox event name. Bitbucket Data Center deliveries arrive with their
+   * Cloud-normalized key (`pr:opened` → `pullrequest:created`) next to the
+   * raw DC payload.
+   */
+  eventType: string;
+  payload: Record<string, unknown>;
+  /** `cont:` key, or `undefined` when the delivery stamps `evt:`. */
+  expectedKey: string | undefined;
+}
+
+export interface ScmDefaultSelectorFixture {
+  kind: "gitlab" | "bitbucket";
+  eventTypes: readonly string[];
+  expected: string;
+}
+
+const GITLAB_PROJECT = {
+  id: 1234,
+  name: "api",
+  path_with_namespace: "Acme/platform/api",
+  web_url: "https://gitlab.com/Acme/platform/api",
+  default_branch: "main",
+};
+
+const GITLAB_MERGE_REQUEST = {
+  id: 9001,
+  iid: 42,
+  title: "Add widgets",
+  state: "opened",
+  source_branch: "feature/widgets",
+  target_branch: "main",
+  url: "https://gitlab.com/Acme/platform/api/-/merge_requests/42",
+  last_commit: { id: "0123456789abcdef0123456789abcdef01234567" },
+};
+
+const BITBUCKET_CLOUD_REPOSITORY = {
+  type: "repository",
+  full_name: "acme/widgets",
+  name: "widgets",
+  uuid: "{5f2d1d5e-6d66-4f5b-9d3e-1b6e5b1c2f3a}",
+  workspace: { slug: "acme", uuid: "{a4f1c5d0-1111-4a2b-8c3d-9e0f1a2b3c4d}" },
+  links: { html: { href: "https://bitbucket.org/acme/widgets" } },
+};
+
+const BITBUCKET_DC_REPOSITORY = {
+  slug: "widgets",
+  id: 17,
+  name: "widgets",
+  project: { key: "ACME", id: 3, name: "Acme" },
+};
+
+export const SCM_CONTINUATION_FIXTURES: readonly ScmContinuationFixture[] = [
+  {
+    name: "gitlab merge_request open",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "merge_request",
+    payload: {
+      object_kind: "merge_request",
+      event_type: "merge_request",
+      user: { id: 7, username: "alice", name: "Alice" },
+      project: GITLAB_PROJECT,
+      object_attributes: { ...GITLAB_MERGE_REQUEST, action: "open" },
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab merge_request update (new commits)",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "merge_request",
+    payload: {
+      object_kind: "merge_request",
+      event_type: "merge_request",
+      user: { id: 7, username: "alice", name: "Alice" },
+      project: GITLAB_PROJECT,
+      object_attributes: {
+        ...GITLAB_MERGE_REQUEST,
+        action: "update",
+        oldrev: "fedcba9876543210fedcba9876543210fedcba98",
+      },
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab note on merge request",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "note",
+    payload: {
+      object_kind: "note",
+      event_type: "note",
+      user: { id: 8, username: "bob", name: "Bob" },
+      project: GITLAB_PROJECT,
+      object_attributes: {
+        id: 501,
+        note: "Looks good",
+        noteable_type: "MergeRequest",
+        noteable_id: 9001,
+      },
+      merge_request: GITLAB_MERGE_REQUEST,
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab note on issue",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "note",
+    payload: {
+      object_kind: "note",
+      event_type: "note",
+      user: { id: 8, username: "bob", name: "Bob" },
+      project: GITLAB_PROJECT,
+      object_attributes: {
+        id: 502,
+        note: "Tracking",
+        noteable_type: "Issue",
+        noteable_id: 300,
+      },
+      issue: { id: 300, iid: 9, title: "Bug" },
+    },
+    expectedKey: undefined,
+  },
+  {
+    name: "gitlab pipeline attached to a merge request",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "pipeline",
+    payload: {
+      object_kind: "pipeline",
+      project: GITLAB_PROJECT,
+      object_attributes: { id: 77, status: "success", sha: "0123456789ab" },
+      merge_request: { iid: 42, id: 9001, title: "Add widgets" },
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab pipeline without a merge request",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "pipeline",
+    payload: {
+      object_kind: "pipeline",
+      project: GITLAB_PROJECT,
+      object_attributes: { id: 78, status: "success", sha: "0123456789ab" },
+      merge_request: null,
+    },
+    expectedKey: undefined,
+  },
+  {
+    name: "gitlab push",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "push",
+    payload: {
+      object_kind: "push",
+      event_name: "push",
+      ref: "refs/heads/main",
+      project: GITLAB_PROJECT,
+      commits: [],
+    },
+    expectedKey: undefined,
+  },
+  {
+    name: "bitbucket cloud pullrequest:created",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "pullrequest:created",
+    payload: {
+      repository: BITBUCKET_CLOUD_REPOSITORY,
+      actor: { display_name: "Alice", uuid: "{u-1}" },
+      pullrequest: {
+        id: 7,
+        title: "Add widgets",
+        state: "OPEN",
+        source: {
+          branch: { name: "feature/widgets" },
+          commit: { hash: "0123456789ab" },
+        },
+        destination: { branch: { name: "main" }, commit: { hash: "fedcba98" } },
+        links: {
+          html: { href: "https://bitbucket.org/acme/widgets/pull-requests/7" },
+        },
+      },
+    },
+    expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+  },
+  {
+    name: "bitbucket data center pr:opened (normalized to pullrequest:created)",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "pullrequest:created",
+    payload: {
+      eventKey: "pr:opened",
+      date: "2026-09-01T12:00:00+0000",
+      actor: { name: "alice", displayName: "Alice", id: 1 },
+      pullRequest: {
+        id: 7,
+        title: "Add widgets",
+        state: "OPEN",
+        open: true,
+        fromRef: {
+          id: "refs/heads/feature/widgets",
+          displayId: "feature/widgets",
+          latestCommit: "0123456789ab",
+          repository: BITBUCKET_DC_REPOSITORY,
+        },
+        toRef: {
+          id: "refs/heads/main",
+          displayId: "main",
+          latestCommit: "fedcba98",
+          repository: BITBUCKET_DC_REPOSITORY,
+        },
+      },
+    },
+    expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+  },
+  {
+    name: "bitbucket cloud pullrequest:comment_created",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "pullrequest:comment_created",
+    payload: {
+      repository: BITBUCKET_CLOUD_REPOSITORY,
+      actor: { display_name: "Bob", uuid: "{u-2}" },
+      pullrequest: { id: 7, title: "Add widgets", state: "OPEN" },
+      comment: { id: 11, content: { raw: "Looks good" } },
+    },
+    expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+  },
+  {
+    name: "bitbucket cloud repo:push",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "repo:push",
+    payload: {
+      repository: BITBUCKET_CLOUD_REPOSITORY,
+      actor: { display_name: "Alice", uuid: "{u-1}" },
+      push: { changes: [] },
+    },
+    expectedKey: undefined,
+  },
+];
+
+export const SCM_DEFAULT_SELECTOR_FIXTURES: readonly ScmDefaultSelectorFixture[] =
+  [
+    { kind: "gitlab", eventTypes: ["merge_request"], expected: "gitlab.mr/v2" },
+    {
+      kind: "gitlab",
+      eventTypes: ["merge_request", "note"],
+      expected: "gitlab.mr/v2",
+    },
+    {
+      kind: "gitlab",
+      eventTypes: ["merge_request", "push"],
+      expected: "gitlab.none/v2",
+    },
+    {
+      kind: "bitbucket",
+      eventTypes: ["pullrequest:created", "pullrequest:updated"],
+      expected: "bitbucket.pr/v2",
+    },
+    {
+      kind: "bitbucket",
+      eventTypes: ["pullrequest:created", "repo:push"],
+      expected: "bitbucket.none/v2",
+    },
+  ];

package/src/internal/workspace-sync.ts

@@ -0,0 +1,55 @@
+/**
+ * Sync `agent/sandbox/workspace/**` seed files onto an Agent Store so
+ * cloud-runtime turns read them from the store mount (the first cloud prompt
+ * names the directory; see `buildCloudWorkspaceSection`). Hosted deployments
+ * write store-root `workspace/<path>`. Local `serve`/`run` with
+ * `runtime: "cloud"` writes `agent-serve/<agent>/workspace/<path>` on the
+ * USER store.
+ */
+
+import { readFile } from "node:fs/promises";
+import { agentStoreKeys, type FileSink } from "../files.js";
+import { MEMORY_DIR_NAME } from "../memory.js";
+import type { SeedFile } from "../types.js";
+import { mirrorToStore, storeRelPath } from "./store-mirror.js";
+
+/**
+ * Mirror the seed tree onto the store at its authored relative paths and
+ * delete keys no seed claims so redeploys drop removed files. Every seed
+ * loads and validates before the store is touched.
+ */
+export async function syncWorkspaceToStore(args: {
+  sink: FileSink;
+  seedFiles: readonly SeedFile[];
+  /** Store-root directory that holds the seed tree. Defaults to `workspace/`. */
+  workspacePrefix?: string;
+}): Promise<void> {
+  const workspacePrefix =
+    args.workspacePrefix ?? agentStoreKeys.workspacePrefix();
+  const desired = new Map<string, Uint8Array>();
+  for (const seed of args.seedFiles) {
+    desired.set(
+      agentStoreKeys.workspaceFile(
+        seedRelPath(seed.relativePath),
+        workspacePrefix
+      ),
+      await readFile(seed.sourcePath)
+    );
+  }
+  await mirrorToStore({ sink: args.sink, prefix: workspacePrefix, desired });
+}
+
+/**
+ * Same reservation as local materialization's `resolveWorkspaceWritePath`:
+ * `memory/` is the shared cross-session journal, so a seed under it fails
+ * the sync exactly as it fails a local first turn.
+ */
+function seedRelPath(relPath: string): string {
+  const rel = storeRelPath(relPath, "workspace file");
+  if (rel.split("/", 1)[0] === MEMORY_DIR_NAME) {
+    throw new Error(
+      `"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to sync ${relPath}`
+    );
+  }
+  return rel;
+}

package/src/internal/workspace.ts

@@ -66,6 +66,20 @@ export function buildCloudMemorySection(agentName: string): string {
   ].join("\n");
 }
 
+/**
+ * First-turn preamble section for cloud-runtime sessions with authored
+ * `agent/sandbox/workspace/**` seeds. Cloud VMs get no materialized
+ * workspace; the seeds are synced onto the store mount instead (see
+ * `syncWorkspaceToStore`), so the model has to be told where they are.
+ */
+export function buildCloudWorkspaceSection(dir: string): string {
+  return [
+    "## Workspace files",
+    "",
+    `The agent's authored workspace files live at \`${dir}\` on this machine. Relative paths in your instructions that name these files resolve under that directory rather than your working directory. Read them with your normal file tools. The directory is shared across sessions, so copy a file into your working directory before editing it.`,
+  ].join("\n");
+}
+
 /** Relative path of an agent-side tool script inside the session workspace. */
 export function agentToolScriptPath(toolName: string): string {
   return `.agent-serve/tools/${toolName}.sh`;

package/src/otel.ts

@@ -9,9 +9,13 @@
  *   serviceName: "cursor",
  *   exporters: [{ url: "https://otel.example.com", protocol: "http/protobuf" }],
  * });
+ *
+ * // Hosted v2: re-read env on flush after deployment secrets bind.
+ * export default defineOtel(() => resolveMyOtelConfig());
  * ```
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import { context, trace } from "@opentelemetry/api";
 import { brandDefinition } from "./internal/brand.js";
 
@@ -92,8 +96,47 @@ export interface OtelConfig {
 
 export type OtelDefinition = OtelConfig & { readonly __agentServe: "otel" };
 
+/** Re-read authored config after bake (hosted v2 binds secrets later). */
+export type OtelConfigFactory = () => OtelConfig;
+
+/**
+ * Hidden factory on {@link OtelDefinition}. Not enumerable so
+ * `pickAuthoredOtel` compares the bake-time snapshot, not the thunk.
+ */
+export const OTEL_CONFIG_RESOLVE: symbol = Symbol.for(
+  "anysphere.july.otel.configResolve"
+);
+
 /** Author OpenTelemetry export under `agent/otel.ts`. */
-export function defineOtel(config: OtelConfig = {}): OtelDefinition {
+export function defineOtel(
+  config: OtelConfig | OtelConfigFactory = {}
+): OtelDefinition {
+  const resolve: OtelConfigFactory =
+    typeof config === "function" ? config : () => config;
+  const snapshot = resolve();
+  validateOtelConfig(snapshot);
+  const def = brandDefinition("otel", snapshot);
+  Object.defineProperty(def, OTEL_CONFIG_RESOLVE, {
+    value: resolve,
+    enumerable: false,
+  });
+  return def;
+}
+
+/** Invoke a `defineOtel(() => …)` factory, or return the static snapshot. */
+export function resolveOtelDefinition(def: OtelConfig): OtelConfig {
+  const resolve = (
+    def as unknown as Record<symbol, OtelConfigFactory | undefined>
+  )[OTEL_CONFIG_RESOLVE];
+  if (resolve === undefined) {
+    return def;
+  }
+  const next = resolve();
+  validateOtelConfig(next);
+  return next;
+}
+
+function validateOtelConfig(config: OtelConfig): void {
   if (config.exporters !== undefined) {
     for (const exporter of config.exporters) {
       if (typeof exporter.url !== "string" || exporter.url.length === 0) {
@@ -123,7 +166,6 @@ export function defineOtel(config: OtelConfig = {}): OtelDefinition {
     }
   }
   assertSampleRatio(config.traces);
-  return brandDefinition("otel", config);
 }
 
 function assertSignals(signals: OtelSignal[] | undefined): void {
@@ -175,12 +217,17 @@ export function formatTraceparent(spanContext: {
 /**
  * Copy the active span onto outbound headers as W3C `traceparent` and
  * Cursor `backend-traceparent`. No-op when no valid span is active.
+ *
+ * Prefers the Agent SDK ALS (`instrumentHttp`, `runInTurn`,
+ * `runInCall`). Falls back to the `@anysphere/context` process-wide
+ * ALS: `createSpan` does not bind OTel API context, and SPAN keys
+ * are per `@opentelemetry/api` copy.
  */
 export function injectActiveTraceContext(headers: {
   get(name: string): string | null;
   set(name: string, value: string): void;
 }): void {
-  const span = trace.getSpan(context.active());
+  const span = trace.getSpan(context.active()) ?? getContextTracerSpan();
   if (span === undefined) {
     return;
   }
@@ -191,3 +238,96 @@ export function injectActiveTraceContext(headers: {
   headers.set(TRACEPARENT_HEADER, traceparent);
   headers.set(BACKEND_TRACEPARENT_HEADER, traceparent);
 }
+
+/** W3C `traceparent` for the active span, or undefined if none. */
+export function activeTraceparent(): string | undefined {
+  const headers = new Headers();
+  injectActiveTraceContext(headers);
+  return headers.get(TRACEPARENT_HEADER) ?? undefined;
+}
+
+/**
+ * Copy the active span onto every outbound `fetch`. Agents should not
+ * wrap their own Connect / MCP clients for this — `createOtelRuntime`
+ * installs it on `globalThis.fetch` when traces are on.
+ */
+function headersForFetch(
+  input: RequestInfo | URL,
+  init?: RequestInit
+): Headers {
+  // Fetch: `init.headers` replaces `Request` headers. If `init` omits
+  // headers (`fetch(request, { signal })`), keep the Request's.
+  const headers = new Headers(
+    init?.headers !== undefined
+      ? init.headers
+      : input instanceof Request
+        ? input.headers
+        : undefined
+  );
+  injectActiveTraceContext(headers);
+  return headers;
+}
+
+export function instrumentedFetch(base: typeof fetch = fetch): typeof fetch {
+  return (input, init) => {
+    const headers = headersForFetch(input, init);
+    if (input instanceof Request && init === undefined) {
+      return base(new Request(input, { headers }));
+    }
+    return base(input, { ...init, headers });
+  };
+}
+
+const OUTBOUND_FETCH_INSTALLED = Symbol.for(
+  "anysphere.july.otel.outboundFetch"
+);
+
+/** Idempotent. Safe to call from `createOtelRuntime` on every serve. */
+export function installOutboundFetchInstrumentation(): void {
+  const slots = globalThis as unknown as Record<symbol, boolean>;
+  if (slots[OUTBOUND_FETCH_INSTALLED] === true) {
+    return;
+  }
+  slots[OUTBOUND_FETCH_INSTALLED] = true;
+  globalThis.fetch = instrumentedFetch(globalThis.fetch);
+}
+
+/** Must match `@anysphere/context` `ACTIVE_OTEL_SPAN_ALS`. */
+const ACTIVE_OTEL_SPAN_ALS = Symbol.for("anysphere.context.activeOtelSpanAls");
+
+function ensureContextTracerAls(): void {
+  const slots = globalThis as unknown as Record<symbol, unknown>;
+  if (slots[ACTIVE_OTEL_SPAN_ALS] === undefined) {
+    slots[ACTIVE_OTEL_SPAN_ALS] = new AsyncLocalStorage();
+  }
+}
+
+ensureContextTracerAls();
+
+function getContextTracerSpan():
+  | {
+      spanContext: () => {
+        traceId: string;
+        spanId: string;
+        traceFlags: number;
+      };
+    }
+  | undefined {
+  const als = (
+    globalThis as unknown as Record<
+      symbol,
+      {
+        getStore?: () =>
+          | {
+              spanContext: () => {
+                traceId: string;
+                spanId: string;
+                traceFlags: number;
+              };
+            }
+          | undefined;
+      }
+    >
+  )[ACTIVE_OTEL_SPAN_ALS];
+  return als?.getStore?.();
+}

package/src/result.ts

@@ -0,0 +1,36 @@
+/**
+ * `defineResult` — authored at `agent/result.ts`.
+ *
+ * After the model finishes, `commit` runs on the serving host with the
+ * full assistant text. Throw to fail the turn. Parse `ctx.text` however
+ * the agent needs.
+ *
+ * ```ts
+ * import { defineResult } from "@cursor/july/result";
+ *
+ * export default defineResult({
+ *   async commit(ctx) {
+ *     if (ctx.session.purpose === "eval") {
+ *       return;
+ *     }
+ *     await applyDecision(parseDecision(ctx.text), ctx.host);
+ *   },
+ * });
+ * ```
+ */
+
+import { brandDefinition } from "./internal/brand.js";
+import type { ResultConfig, ResultDefinition } from "./types.js";
+
+export type {
+  ResultConfig,
+  ResultContext,
+  ResultDefinition,
+} from "./types.js";
+
+export function defineResult(config: ResultConfig): ResultDefinition {
+  if (typeof config.commit !== "function") {
+    throw new Error("defineResult: commit is required");
+  }
+  return brandDefinition("result", config);
+}

package/src/storage-backends/cursor-hosted.ts

@@ -24,6 +24,7 @@
 
 import type { ABSnapshot } from "../ab.js";
 import type { EvalRunSnapshot } from "../evals.js";
+import { injectActiveTraceContext } from "../otel.js";
 import type {
   StorageABTable,
   StorageCasTable,
@@ -223,12 +224,14 @@ export async function storageRpc<T>(
   if (typeof fetchImpl !== "function") {
     throw new Error("cursorHostedStorage requires fetch");
   }
+  const headers = new Headers({
+    Authorization: `Bearer ${apiKey}`,
+    "Content-Type": "application/json",
+  });
+  injectActiveTraceContext(headers);
   const response = await fetchImpl(`${baseUrl}${path}`, {
     method: "POST",
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      "Content-Type": "application/json",
-    },
+    headers,
     body: JSON.stringify(body),
   });
   const text = await response.text();

package/src/storage-protocol.ts

@@ -7,6 +7,7 @@
  */
 
 import { createHash } from "node:crypto";
+import { isRecord } from "./internal/is-record.js";
 
 /** Legacy architecture-v1 storage root. */
 export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
@@ -205,10 +206,6 @@ export type DurableSessionSummary = {
   running: boolean | undefined;
 };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function stringValue(value: unknown): string | undefined {
   return typeof value === "string" ? value : undefined;
 }