@cursor/july 0.1.102 → 0.1.104

package/dist/internal/testing/scm-continuation-fixtures.js

@@ -0,0 +1,253 @@
+/**
+ * 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.
+ */
+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 = [
+    {
+        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: Object.assign(Object.assign({}, 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: Object.assign(Object.assign({}, 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 = [
+    { 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/dist/internal/workspace-sync.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 { type FileSink } from "../files.js";
+import type { SeedFile } from "../types.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 declare function syncWorkspaceToStore(args: {
+    sink: FileSink;
+    seedFiles: readonly SeedFile[];
+    /** Store-root directory that holds the seed tree. Defaults to `workspace/`. */
+    workspacePrefix?: string;
+}): Promise<void>;
+//# sourceMappingURL=workspace-sync.d.ts.map

package/dist/internal/workspace-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-sync.d.ts","sourceRoot":"","sources":["../../src/internal/workspace-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC/B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAchB"}

package/dist/internal/workspace-sync.js

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { readFile } from "node:fs/promises";
+import { agentStoreKeys } from "../files.js";
+import { MEMORY_DIR_NAME } from "../memory.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 function syncWorkspaceToStore(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const workspacePrefix = (_a = args.workspacePrefix) !== null && _a !== void 0 ? _a : agentStoreKeys.workspacePrefix();
+        const desired = new Map();
+        for (const seed of args.seedFiles) {
+            desired.set(agentStoreKeys.workspaceFile(seedRelPath(seed.relativePath), workspacePrefix), yield readFile(seed.sourcePath));
+        }
+        yield 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) {
+    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/dist/internal/workspace.d.ts

@@ -30,6 +30,13 @@ export interface MaterializeWorkspaceOptions {
  * deployments: cloud VMs read the memory journal from the store mount.
  */
 export declare function buildCloudMemorySection(agentName: string): string;
+/**
+ * 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 declare function buildCloudWorkspaceSection(dir: string): string;
 /** Relative path of an agent-side tool script inside the session workspace. */
 export declare function agentToolScriptPath(toolName: string): string;
 /**

package/dist/internal/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA8CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA6BR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CACX,MAAM,EACN,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CACjE,GACA,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA8CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA6BR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CACX,MAAM,EACN,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CACjE,GACA,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/internal/workspace.js

@@ -37,6 +37,19 @@ export function buildCloudMemorySection(agentName) {
         `The cross-session memory journal (the \`memory/\` directory your instructions may reference) lives at \`${dir}\` on this machine — read \`${dir}/journal.jsonl\` with your normal file tools.`,
     ].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) {
+    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) {
     return `.agent-serve/tools/${toolName}.sh`;

package/dist/otel.d.ts

@@ -9,6 +9,9 @@
  *   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());
  * ```
  */
 export type OtelSignal = "traces" | "metrics" | "logs";
@@ -83,8 +86,17 @@ 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 declare const OTEL_CONFIG_RESOLVE: symbol;
 /** Author OpenTelemetry export under `agent/otel.ts`. */
-export declare function defineOtel(config?: OtelConfig): OtelDefinition;
+export declare function defineOtel(config?: OtelConfig | OtelConfigFactory): OtelDefinition;
+/** Invoke a `defineOtel(() => …)` factory, or return the static snapshot. */
+export declare function resolveOtelDefinition(def: OtelConfig): OtelConfig;
 export declare const TRACEPARENT_HEADER = "traceparent";
 /** Cursor backend prefers this; `remoteSpanContextFromRequest` falls back to W3C. */
 export declare const BACKEND_TRACEPARENT_HEADER = "backend-traceparent";
@@ -96,9 +108,19 @@ export declare 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 declare function injectActiveTraceContext(headers: {
     get(name: string): string | null;
     set(name: string, value: string): void;
 }): void;
+/** W3C `traceparent` for the active span, or undefined if none. */
+export declare function activeTraceparent(): string | undefined;
+export declare function instrumentedFetch(base?: typeof fetch): typeof fetch;
+/** Idempotent. Safe to call from `createOtelRuntime` on every serve. */
+export declare function installOutboundFetchInstrumentation(): void;
 //# sourceMappingURL=otel.d.ts.map

package/dist/otel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,eAAe,CAAC;IACzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C;;;OAGG;IACH,SAAS,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACjC,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACpC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACtC,4DAA4D;IAC5D,IAAI,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;CACjC;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,MAAM,GAAE,UAAe,GAAG,cAAc,CA+BlE;AA+BD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAChD,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE,wBAAgB,iBAAiB,CAAC,WAAW,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,GAAG,SAAS,CAOrB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACjC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC,GAAG,IAAI,CAWP"}
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,eAAe,CAAC;IACzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C;;;OAGG;IACH,SAAS,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACjC,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACpC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,GAAG,iBAAiB,CAAC;IACtC,4DAA4D;IAC5D,IAAI,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;CACjC;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG,MAAM,UAAU,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAEjC,CAAC;AAEF,yDAAyD;AACzD,wBAAgB,UAAU,CACxB,MAAM,GAAE,UAAU,GAAG,iBAAsB,GAC1C,cAAc,CAWhB;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,UAAU,GAAG,UAAU,CAUjE;AA+DD,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAChD,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE,wBAAgB,iBAAiB,CAAC,WAAW,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,GAAG,SAAS,CAOrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACjC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC,GAAG,IAAI,CAWP;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAItD;AAwBD,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,OAAO,KAAa,GAAG,OAAO,KAAK,CAQ1E;AAMD,wEAAwE;AACxE,wBAAgB,mCAAmC,IAAI,IAAI,CAO1D"}

package/dist/otel.js

@@ -9,12 +9,42 @@
  *   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";
+/**
+ * Hidden factory on {@link OtelDefinition}. Not enumerable so
+ * `pickAuthoredOtel` compares the bake-time snapshot, not the thunk.
+ */
+export const OTEL_CONFIG_RESOLVE = Symbol.for("anysphere.july.otel.configResolve");
 /** Author OpenTelemetry export under `agent/otel.ts`. */
 export function defineOtel(config = {}) {
+    const resolve = 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) {
+    const resolve = def[OTEL_CONFIG_RESOLVE];
+    if (resolve === undefined) {
+        return def;
+    }
+    const next = resolve();
+    validateOtelConfig(next);
+    return next;
+}
+function validateOtelConfig(config) {
     if (config.exporters !== undefined) {
         for (const exporter of config.exporters) {
             if (typeof exporter.url !== "string" || exporter.url.length === 0) {
@@ -36,7 +66,6 @@ export function defineOtel(config = {}) {
         }
     }
     assertSampleRatio(config.traces);
-    return brandDefinition("otel", config);
 }
 function assertSignals(signals) {
     if (signals === undefined) {
@@ -75,9 +104,15 @@ 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) {
-    const span = trace.getSpan(context.active());
+    var _a;
+    const span = (_a = trace.getSpan(context.active())) !== null && _a !== void 0 ? _a : getContextTracerSpan();
     if (span === undefined) {
         return;
     }
@@ -88,3 +123,59 @@ 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() {
+    var _a;
+    const headers = new Headers();
+    injectActiveTraceContext(headers);
+    return (_a = headers.get(TRACEPARENT_HEADER)) !== null && _a !== void 0 ? _a : 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, init) {
+    // Fetch: `init.headers` replaces `Request` headers. If `init` omits
+    // headers (`fetch(request, { signal })`), keep the Request's.
+    const headers = new Headers((init === null || init === void 0 ? void 0 : init.headers) !== undefined
+        ? init.headers
+        : input instanceof Request
+            ? input.headers
+            : undefined);
+    injectActiveTraceContext(headers);
+    return headers;
+}
+export function instrumentedFetch(base = fetch) {
+    return (input, init) => {
+        const headers = headersForFetch(input, init);
+        if (input instanceof Request && init === undefined) {
+            return base(new Request(input, { headers }));
+        }
+        return base(input, Object.assign(Object.assign({}, init), { headers }));
+    };
+}
+const OUTBOUND_FETCH_INSTALLED = Symbol.for("anysphere.july.otel.outboundFetch");
+/** Idempotent. Safe to call from `createOtelRuntime` on every serve. */
+export function installOutboundFetchInstrumentation() {
+    const slots = globalThis;
+    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() {
+    const slots = globalThis;
+    if (slots[ACTIVE_OTEL_SPAN_ALS] === undefined) {
+        slots[ACTIVE_OTEL_SPAN_ALS] = new AsyncLocalStorage();
+    }
+}
+ensureContextTracerAls();
+function getContextTracerSpan() {
+    var _a;
+    const als = globalThis[ACTIVE_OTEL_SPAN_ALS];
+    return (_a = als === null || als === void 0 ? void 0 : als.getStore) === null || _a === void 0 ? void 0 : _a.call(als);
+}