@cursor/july 0.1.101 → 0.1.103

package/src/otel.ts

@@ -9,9 +9,14 @@
  *   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";
 
 export type OtelSignal = "traces" | "metrics" | "logs";
@@ -91,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) {
@@ -122,7 +166,6 @@ export function defineOtel(config: OtelConfig = {}): OtelDefinition {
     }
   }
   assertSampleRatio(config.traces);
-  return brandDefinition("otel", config);
 }
 
 function assertSignals(signals: OtelSignal[] | undefined): void {
@@ -153,3 +196,138 @@ function assertSampleRatio(traces: OtelConfig["traces"]): void {
     throw new Error("defineOtel: traces.sampleRatio must be in [0, 1]");
   }
 }
+
+export const TRACEPARENT_HEADER = "traceparent";
+/** Cursor backend prefers this; `remoteSpanContextFromRequest` falls back to W3C. */
+export const BACKEND_TRACEPARENT_HEADER = "backend-traceparent";
+
+export function formatTraceparent(spanContext: {
+  traceId: string;
+  spanId: string;
+  traceFlags: number;
+}): string | undefined {
+  if (!trace.isSpanContextValid(spanContext)) {
+    return undefined;
+  }
+  return `00-${spanContext.traceId}-${
+    spanContext.spanId
+  }-${spanContext.traceFlags.toString(16).padStart(2, "0")}`;
+}
+
+/**
+ * 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()) ?? getContextTracerSpan();
+  if (span === undefined) {
+    return;
+  }
+  const traceparent = formatTraceparent(span.spanContext());
+  if (traceparent === undefined) {
+    return;
+  }
+  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

@@ -1,119 +1,130 @@
 /**
  * Durable session KV contract: key families plus a tolerant SessionRecord
- * decoder. This is the lockstep surface for the control plane (see
- * `backend/server/src/agentServe/durableSessionProtocol.ts`) so a dashboard
- * list can read Bugbot KV without importing `@cursor/july`.
+ * decoder. Architecture v1 remains in lockstep with the Bugbot-backed control
+ * plane. Architecture v2 uses the same key shape under its AgentSDK root.
  *
  * Additive JSON only — unknown fields are ignored.
  */
 
 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;
 
 /**
- * Framework-owned key root. All {@link storageKeys} values live under this
- * prefix so a shared store can route or namespace Agent SDK data.
+ * Architecture-v2 storage root. Hard cutoff: v2 writes and reads this
+ * prefix only. Existing `agentkit/v1` v2 objects are not migrated.
  */
-export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
+export const AGENTSDK_STORAGE_KEY_ROOT = "agentsdk/v1" as const;
 
 /**
- * Exact session-record keys: `agentkit/v1/{agent}/session/{sessionId}`.
+ * Exact session-record keys: `{agentkit|agentsdk}/v1/{agent}/session/{sessionId}`.
  * Rejects `session-events/` and the CP-owned `_cp` agent name.
  */
 const DURABLE_SESSION_RECORD_KEY_RE =
-  /^agentkit\/v1\/([^/]+)\/session\/([^/]+)$/;
+  /^(agentkit|agentsdk)\/v1\/([^/]+)\/session\/([^/]+)$/;
 
 /**
- * The framework-owned key scheme. Keys are a **stable, versioned contract**
- * under {@link STORAGE_KEY_ROOT}: sinks may treat them as opaque strings, or
- * route on prefixes (e.g. event chunks to object storage, everything else
- * to a database). Channel ids and continuation tokens are the only segments
- * that may contain caller-controlled characters; they are URI-encoded, and
- * a segment whose encoding exceeds {@link MAX_KEY_SEGMENT_BYTES} is replaced
- * by a `sha256:…` digest — so every minted key has a bounded length that any
- * backend (VARCHAR columns, btree index tuples, S3 key limits) can store,
- * no matter what a caller stuffs into a token. The substitution is
- * deterministic: writes and continuation lookups build the same key.
+ * Build the framework-owned key scheme under one versioned root. Channel ids
+ * and continuation tokens are URI-encoded, and oversized segments are
+ * replaced by a deterministic `sha256:…` digest.
  *
  * | Key | Value |
  * | --- | --- |
- * | `agentkit/v1/{agent}/session/{sessionId}` | `SessionRecord` |
- * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
- * | `agentkit/v1/{agent}/session-runs/{sessionPublicId}` | One session-level hosted-execution log (executions[] + lastFailure) |
- * | `agentkit/v1/{agent}/logs/{logId}` | Hosted engine stdout/stderr tee (on-disk `start.log`; `ses_…` after send, `wf:{workflowId}` on admission failure) |
- * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
- * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
+ * | `{root}/{agent}/session/{sessionId}` | `SessionRecord` |
+ * | `{root}/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
+ * | `{root}/{agent}/session-runs/{sessionPublicId}` | One session-level hosted-execution log (executions[] + lastFailure) |
+ * | `{root}/{agent}/logs/{logId}` | Hosted engine stdout/stderr tee (on-disk `start.log`; `ses_…` after send, `wf:{workflowId}` on admission failure) |
+ * | `{root}/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
+ * | `{root}/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
  *
  * The `eval-runs` / `ab-samples` / `ab-snapshot` families are minted only
  * by the tables `defineStorage` derives over the KV core; a backend that
  * authors dedicated `StorageConfig.evals` / `StorageConfig.abs` groups never
  * sees them.
  */
-export const storageKeys = {
-  session: (agent: string, sessionId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session/${sessionId}`,
-  sessionPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session/`,
-  sessionEvents: (
-    agent: string,
-    sessionId: string,
-    firstIndex: number
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
-  sessionEventsPrefix: (agent: string, sessionId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/`,
-  /**
-   * One session-level hosted-execution log (v2 only). `sessionPublicId` is
-   * the factory `ses_…` so a throw that never minted a July session still
-   * lands under a stable key. Per-execution rows live inside the document.
-   */
-  sessionRun: (agent: string, sessionPublicId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session-runs/${keySegment(sessionPublicId)}`,
-  sessionRunsPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session-runs/`,
-  /**
-   * The v2 customer log: the engine stdout/stderr tee (on-disk `start.log`).
-   * `logId` is the factory `ses_…` after a `send`, or
-   * `wf:{workflowId}` / `wf:{workflowId}/{runId}` when admission fails
-   * before a session exists. Skip/task admissions do not write this key.
-   * Stored as raw UTF-8, not JSON — the file store accepts 64 MiB
-   * objects, and this key is flushed in snapshots, not per line.
-   */
-  log: (agent: string, logId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/logs/${keySegment(logId)}`,
-  logsPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/logs/`,
-  continuation: (
-    agent: string,
-    channelId: string,
-    continuationKey: string
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
-  /**
-   * Author-facing opaque JSON (see `HostContext.kv`). `key` is URI-encoded /
-   * digested like other caller-controlled segments.
-   */
-  kv: (agent: string, key: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/kv/${keySegment(key)}`,
-  kvPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/kv/`,
-  /** One playground eval-run snapshot (derived `evals` table). */
-  evalRun: (agent: string, runId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/${keySegment(runId)}`,
-  evalRunsPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/`,
-  /**
-   * One A/B metric sample (derived `abs` table); the segments mirror the
-   * dedicated table's row identity (experiment + sessionId + at).
-   */
-  abSample: (
-    agent: string,
-    experiment: string,
-    sessionId: string,
-    at: string
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/ab-samples/${keySegment(experiment)}/${keySegment(sessionId)}/${keySegment(at)}`,
-  /** Latest aggregate A/B snapshot (derived `abs` table, LWW). */
-  abSnapshot: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/ab-snapshot`,
-} as const;
+function createStorageKeys(root: string) {
+  return {
+    session: (agent: string, sessionId: string): string =>
+      `${root}/${agent}/session/${sessionId}`,
+    sessionPrefix: (agent: string): string => `${root}/${agent}/session/`,
+    sessionEvents: (
+      agent: string,
+      sessionId: string,
+      firstIndex: number
+    ): string =>
+      `${root}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
+    sessionEventsPrefix: (agent: string, sessionId: string): string =>
+      `${root}/${agent}/session-events/${sessionId}/`,
+    /**
+     * One session-level hosted-execution log (v2 only). `sessionPublicId` is
+     * the factory `ses_…` so a throw that never minted a July session still
+     * lands under a stable key. Per-execution rows live inside the document.
+     */
+    sessionRun: (agent: string, sessionPublicId: string): string =>
+      `${root}/${agent}/session-runs/${keySegment(sessionPublicId)}`,
+    sessionRunsPrefix: (agent: string): string =>
+      `${root}/${agent}/session-runs/`,
+    /**
+     * The v2 customer log: the engine stdout/stderr tee (on-disk `start.log`).
+     * `logId` is the factory `ses_…` after a `send`, or
+     * `wf:{workflowId}` / `wf:{workflowId}/{runId}` when admission fails
+     * before a session exists. Skip/task admissions do not write this key.
+     * Stored as raw UTF-8, not JSON — the file store accepts 64 MiB
+     * objects, and this key is flushed in snapshots, not per line.
+     */
+    log: (agent: string, logId: string): string =>
+      `${root}/${agent}/logs/${keySegment(logId)}`,
+    logsPrefix: (agent: string): string => `${root}/${agent}/logs/`,
+    continuation: (
+      agent: string,
+      channelId: string,
+      continuationKey: string
+    ): string =>
+      `${root}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
+    /**
+     * Author-facing opaque JSON (see `HostContext.kv`). `key` is URI-encoded /
+     * digested like other caller-controlled segments.
+     */
+    kv: (agent: string, key: string): string =>
+      `${root}/${agent}/kv/${keySegment(key)}`,
+    kvPrefix: (agent: string): string => `${root}/${agent}/kv/`,
+    /** One playground eval-run snapshot (derived `evals` table). */
+    evalRun: (agent: string, runId: string): string =>
+      `${root}/${agent}/eval-runs/${keySegment(runId)}`,
+    evalRunsPrefix: (agent: string): string => `${root}/${agent}/eval-runs/`,
+    /**
+     * One A/B metric sample (derived `abs` table); the segments mirror the
+     * dedicated table's row identity (experiment + sessionId + at).
+     */
+    abSample: (
+      agent: string,
+      experiment: string,
+      sessionId: string,
+      at: string
+    ): string =>
+      `${root}/${agent}/ab-samples/${keySegment(experiment)}/${keySegment(sessionId)}/${keySegment(at)}`,
+    /** Latest aggregate A/B snapshot (derived `abs` table, LWW). */
+    abSnapshot: (agent: string): string => `${root}/${agent}/ab-snapshot`,
+  } as const;
+}
+
+export type StorageKeys = ReturnType<typeof createStorageKeys>;
+
+/** Architecture-v1 keys. Kept stable for existing deployments. */
+export const storageKeys: StorageKeys = createStorageKeys(STORAGE_KEY_ROOT);
+
+/** Architecture-v2 keys. Hard cutoff onto {@link AGENTSDK_STORAGE_KEY_ROOT}. */
+export const agentSdkStorageKeys: StorageKeys = createStorageKeys(
+  AGENTSDK_STORAGE_KEY_ROOT
+);
+
+export function storageKeysForArchitecture(
+  architecture: "v1" | "v2" | undefined
+): StorageKeys {
+  return architecture === "v2" ? agentSdkStorageKeys : storageKeys;
+}
 
 /**
  * Max bytes a caller-controlled key segment may occupy after URI-encoding.
@@ -164,7 +175,7 @@ export function keySegment(raw: string): string {
 
 export function isDurableSessionRecordKey(key: string): boolean {
   const match = DURABLE_SESSION_RECORD_KEY_RE.exec(key);
-  return match !== null && match[1] !== "_cp";
+  return match !== null && match[2] !== "_cp";
 }
 
 /** List fields of a persisted `SessionRecord`. Unknown properties are dropped. */
@@ -195,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;
 }

package/src/storage.ts

@@ -61,8 +61,11 @@ import type { JsonValue, KvCasResult, KvVersionedEntry } from "./types.js";
 export type {
   DurableSessionRecord,
   DurableSessionSummary,
+  StorageKeys,
 } from "./storage-protocol.js";
 export {
+  AGENTSDK_STORAGE_KEY_ROOT,
+  agentSdkStorageKeys,
   frameworkStartLogId,
   GOLDEN_DURABLE_SESSION_RECORD,
   isDurableSessionRecordKey,
@@ -71,6 +74,7 @@ export {
   parseDurableSessionRecord,
   STORAGE_KEY_ROOT,
   storageKeys,
+  storageKeysForArchitecture,
   summarizeDurableSessionRecord,
 } from "./storage-protocol.js";
 

package/src/tools.ts

@@ -53,7 +53,13 @@
  */
 
 import type { z } from "zod";
+import {
+  forwardTimeArgument,
+  missingTimeWindow,
+  schemaTimeWindowKeys,
+} from "./internal/as-of.js";
 import { brandDefinition } from "./internal/brand.js";
+import { classifyAnnotationsEffect } from "./internal/tool-policy.js";
 import type {
   JsonObject,
   JsonSchemaObject,
@@ -78,6 +84,18 @@ export type {
   ToolNeedsApproval,
   ToolResultContent,
 } from "./types.js";
+/**
+ * Time-window and effect classifiers the host applies to every tool call.
+ * Re-exported for tools that reach other tools themselves (change-monitor
+ * `script`): inner calls skip the host gate, so the sandbox applies the same
+ * forward-time, omitted-window, and read-only filters.
+ */
+export {
+  classifyAnnotationsEffect,
+  forwardTimeArgument,
+  missingTimeWindow,
+  schemaTimeWindowKeys,
+};
 
 /** Input type for `execute`: inferred from a zod schema, JSON otherwise. */
 export type ToolInput<TSchema> = TSchema extends z.ZodTypeAny