@cursor/july 0.1.102 → 0.1.103

package/src/internal/init-project.ts

@@ -1,5 +1,5 @@
 /**
- * Scaffold a minimal agent-serve project (`agent-serve init`).
+ * Scaffold a minimal agent-serve project (`agent-sdk init`).
  */
 
 import { spawn } from "node:child_process";
@@ -702,7 +702,7 @@ export function initNextCommands(options: {
 }
 
 /**
- * Coding-agent setup guide printed by `agent-serve init`
+ * Coding-agent setup guide printed by `agent-sdk init`
  * with no target directory (does not scaffold).
  */
 export function printInitGuide(): void {

package/src/internal/inline-stdio-define-stub.ts

@@ -1,4 +1,4 @@
-/** Bundled stand-in for `@anysphere/agent-serve/connections` / `@cursor/july/connections`. */
+/** Bundled stand-in for `@cursor/july/connections`. */
 export function defineConnection<T>(config: T): T {
   return config;
 }

package/src/internal/is-record.ts

@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/internal/json-schema.ts

@@ -13,12 +13,13 @@ export function isZodSchema(value: unknown): value is z.ZodTypeAny {
     return true;
   }
   // Structural check for zod instances that come from a different module
-  // copy in the authoring project's node_modules.
+  // copy in the authoring project's node_modules. Zod 4 keeps `_zod`
+  // (and often `_def`).
   return (
     typeof value === "object" &&
     value !== null &&
     typeof (value as { safeParse?: unknown }).safeParse === "function" &&
-    "_def" in value
+    ("_def" in value || "_zod" in value)
   );
 }
 
@@ -50,15 +51,23 @@ export function toolOutputJsonSchema(
 function authoredSchemaToJsonSchema(
   schema: z.ZodTypeAny | JsonSchemaObject
 ): JsonSchemaObject {
-  if (isZodSchema(schema)) {
-    const converted = zodToJsonSchema(schema as z.ZodTypeAny, {
-      $refStrategy: "none",
-      target: "jsonSchema7",
-    }) as Record<string, unknown>;
-    delete converted.$schema;
-    return converted;
+  if (!isZodSchema(schema)) {
+    return schema;
   }
-  return schema;
+  const converted = convertZodSchema(schema);
+  delete converted.$schema;
+  return converted;
+}
+
+function convertZodSchema(schema: z.ZodTypeAny): Record<string, unknown> {
+  const native = (schema as { toJSONSchema?: () => unknown }).toJSONSchema;
+  if (typeof native === "function") {
+    return native.call(schema) as Record<string, unknown>;
+  }
+  return zodToJsonSchema(schema, {
+    $refStrategy: "none",
+    target: "jsonSchema7",
+  }) as Record<string, unknown>;
 }
 
 export type ToolInputValidation =

package/src/internal/local-control-plane.ts

@@ -9,7 +9,7 @@
  * Hosted `--no-control-plane` v2 skips that poll — the hosted CP delivers.
  */
 
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { type CronExpression, parseCron } from "./cron.js";
 import {
   type LocalIngressContinuation,
@@ -43,8 +43,7 @@ export async function createLocalControlPlane(opts: {
   fireReminder: (id: string, fireCount: number) => Promise<unknown>;
   /**
    * Persist reminder documents under `<stateDir>/reminders`. Local serve
-   * passes `<stateRoot>/control-plane`; records previously stored at
-   * `<stateRoot>/reminders` are migrated in on first boot.
+   * passes `<stateRoot>/control-plane`.
    */
   stateDir?: string;
   /** Arm deadline timers. Off in `--dev`. Defaults to true. */
@@ -59,31 +58,13 @@ export async function createLocalControlPlane(opts: {
       : new ReminderStore(join(opts.stateDir, "reminders"));
   const schedules = new Map<string, CronExpression>();
   const reminderTimers = new Map<string, NodeJS.Timeout>();
-  const reminders = new Map<string, ReminderRecord>();
+  const reminders = new Map<string, ReminderRecord>(
+    ((await store?.list()) ?? []).map((record) => [record.id, record])
+  );
   let scheduleTimer: NodeJS.Timeout | undefined;
   let lastFiredMinute = -1;
   let scmRelay: { start(): void; stop(): Promise<void> } | undefined;
 
-  if (store !== undefined) {
-    for (const record of await store.list()) {
-      reminders.set(record.id, record);
-    }
-    if (opts.stateDir !== undefined) {
-      const legacyStore = new ReminderStore(
-        join(dirname(opts.stateDir), "reminders")
-      );
-      for (const record of await legacyStore.list()) {
-        if (reminders.has(record.id)) {
-          await legacyStore.delete(record.id);
-          continue;
-        }
-        reminders.set(record.id, record);
-        await store.save(record);
-        await legacyStore.delete(record.id);
-      }
-    }
-  }
-
   function armScheduleTicker(): void {
     if (scheduleTimer !== undefined || schedules.size === 0) {
       return;

package/src/internal/mcp-endpoint.ts

@@ -37,6 +37,7 @@ import type {
   TurnOutcome,
 } from "../types.js";
 import { samePrincipal } from "./auth.js";
+import { describeError } from "./describe-error.js";
 import {
   SessionBusyError,
   type SessionEngine,
@@ -790,7 +791,3 @@ function raceTimeout<T>(
     );
   });
 }
-
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/internal/otel/collector.ts

@@ -12,6 +12,7 @@ import {
   type Counter,
   context,
   type Meter,
+  ROOT_CONTEXT,
   type Span,
   SpanKind,
   SpanStatusCode,
@@ -24,10 +25,13 @@ import type { OtelRuntime } from "./runtime.js";
 
 const CONTENT_MAX = 2_048;
 
-export interface OtelCallContext {
+export interface OtelTurnContext {
   sessionId: string;
   session: SessionInfo;
   turnId: string;
+}
+
+export interface OtelCallContext extends OtelTurnContext {
   callId: string;
   toolName: string;
 }
@@ -35,10 +39,17 @@ export interface OtelCallContext {
 export interface OtelCollector {
   onEvent(event: SessionEvent, session: SessionInfo): void;
   close(): void;
+  /**
+   * Run `fn` under the turn span so outbound inject sees that context.
+   * Host files / VFS / Factory RPCs during `runner.runTurn` are not
+   * inside `runInCall`. Opens the turn if `turn.started` has not been
+   * applied yet (dispatch is async).
+   */
+  runInTurn<T>(args: OtelTurnContext, fn: () => T | Promise<T>): Promise<T>;
   /**
    * Run `fn` under the tool span so outbound inject sees that context.
-   * Opens the session / turn / tool span if the event stream has not
-   * reached `actions.requested` yet (dispatch is async).
+   * Opens the turn / tool span if the event stream has not reached
+   * `actions.requested` yet (dispatch is async).
    */
   runInCall<T>(args: OtelCallContext, fn: () => T | Promise<T>): Promise<T>;
   /** Merge author tags onto the session; paints open spans immediately. */
@@ -60,9 +71,10 @@ interface TurnState {
   synthetic: boolean;
 }
 
+/** Per-conversation bag for in-flight turns. No session span — those
+ * stay open across `session.waiting` and never export on hosted
+ * conversational agents. Each turn is its own root. */
 interface SessionState {
-  span: Span;
-  ctx: Context;
   turns: Map<string, TurnState>;
 }
 
@@ -91,8 +103,11 @@ export function createOtelCollector(
     },
     close() {
       for (const [sessionId, state] of sessions) {
-        state.span.setStatus({ code: SpanStatusCode.UNSET });
-        state.span.end();
+        for (const turn of state.turns.values()) {
+          endOpenChildren(turn, undefined);
+          turn.span.setStatus({ code: SpanStatusCode.UNSET });
+          turn.span.end();
+        }
         sessions.delete(sessionId);
       }
       extraBySession.clear();
@@ -107,6 +122,12 @@ export function createOtelCollector(
       const bag = extraBySession.get(sessionId);
       return bag === undefined ? undefined : { ...bag };
     },
+    runInTurn(args, fn) {
+      const span = ensureTurnSpan(args);
+      return context.with(trace.setSpan(context.active(), span), () =>
+        Promise.resolve(fn())
+      );
+    },
     runInCall(args, fn) {
       const span = ensureCallSpan(args);
       return context.with(trace.setSpan(context.active(), span), () =>
@@ -121,49 +142,35 @@ export function createOtelCollector(
 
     switch (event.type) {
       case "session.started": {
-        if (sessions.get(event.sessionId) !== undefined) {
+        if (sessions.has(event.sessionId)) {
           return;
         }
-        openSession({
-          sessionId: event.sessionId,
-          session,
-          channelId: event.data.channelId,
-          startTime,
-          restored: false,
-        });
+        sessionState(event.sessionId);
+        metrics?.sessions.add(
+          1,
+          join(event.sessionId, {
+            "agent_sdk.agent": agentName,
+            "agent_sdk.channel": event.data.channelId,
+          })
+        );
         return;
       }
       case "agent.bound": {
-        const state = ensureSession(event, session, startTime);
-        if (state === undefined) {
+        const painted = attrs({
+          "agent_sdk.sdk_agent_id": event.data.sdkAgentId,
+          "agent_sdk.sdk_agent_url":
+            logOpts?.toolContent === true ? event.data.url : undefined,
+        });
+        if (Object.keys(painted).length === 0) {
           return;
         }
-        state.span.setAttribute(
-          "agent_sdk.sdk_agent_id",
-          event.data.sdkAgentId
-        );
-        // URL can identify a deployment; keep it off spans unless opted in.
-        if (logOpts?.toolContent === true && event.data.url !== undefined) {
-          state.span.setAttribute("agent_sdk.sdk_agent_url", event.data.url);
-        }
+        const bag = extraBySession.get(event.sessionId) ?? {};
+        Object.assign(bag, painted);
+        extraBySession.set(event.sessionId, bag);
+        paintOpenSpans(event.sessionId, painted);
         return;
       }
       case "message.received": {
-        const state = ensureSession(event, session, startTime);
-        if (state === undefined) {
-          return;
-        }
-        state.span.addEvent(
-          "message.received",
-          attrs({
-            "agent_sdk.event": "message.received",
-            "agent_sdk.user_prompt":
-              logOpts?.userPrompts === true
-                ? truncate(event.data.text)
-                : undefined,
-          }),
-          startTime
-        );
         emitLog(
           "message.received",
           SeverityNumber.INFO,
@@ -177,26 +184,11 @@ export function createOtelCollector(
         );
         return;
       }
-      case "turn.queued": {
-        ensureSession(event, session, startTime)?.span.addEvent(
-          "turn.queued",
-          attrs({
-            "agent_sdk.turn_id": event.turnId,
-            "agent_sdk.queue_position": event.data.position,
-            "agent_sdk.max_running_turns": event.data.maxRunningTurns,
-          }),
-          startTime
-        );
-        return;
-      }
       case "turn.started": {
         if (event.turnId === undefined) {
           return;
         }
-        const state = ensureSession(event, session, startTime);
-        if (state === undefined) {
-          return;
-        }
+        const state = sessionState(event.sessionId);
         // `runInCall` can open a synthetic turn before this event is
         // applied. Keep that entry (and its in-flight tool spans) and
         // just mark it real so `action.result` will not auto-close it.
@@ -430,16 +422,19 @@ export function createOtelCollector(
         return;
       }
       case "artifact.tagged": {
-        ensureSession(event, session, startTime)?.span.addEvent(
-          "artifact.tagged",
-          attrs({
-            "agent_sdk.artifact_id": event.data.id,
-            "agent_sdk.artifact_kind": event.data.kind,
-            "agent_sdk.artifact_key": event.data.key,
-            "agent_sdk.artifact_source": event.data.source,
-          }),
-          startTime
-        );
+        const state = sessions.get(event.sessionId);
+        if (state === undefined) {
+          return;
+        }
+        const tagged = attrs({
+          "agent_sdk.artifact_id": event.data.id,
+          "agent_sdk.artifact_kind": event.data.kind,
+          "agent_sdk.artifact_key": event.data.key,
+          "agent_sdk.artifact_source": event.data.source,
+        });
+        for (const turn of state.turns.values()) {
+          turn.span.addEvent("artifact.tagged", tagged, startTime);
+        }
         return;
       }
       case "turn.completed": {
@@ -535,14 +530,6 @@ export function createOtelCollector(
         );
         return;
       }
-      case "session.waiting": {
-        ensureSession(event, session, startTime)?.span.addEvent(
-          "session.waiting",
-          undefined,
-          startTime
-        );
-        return;
-      }
       case "session.completed": {
         endSession({
           sessionId: event.sessionId,
@@ -575,68 +562,13 @@ export function createOtelCollector(
     }
   }
 
-  /**
-   * Open a session span on first live event after restore/resume (no
-   * `session.started` in this process). Fresh sessions still use the
-   * dedicated `session.started` case.
-   */
-  function ensureSession(
-    event: SessionEvent,
-    session: SessionInfo,
-    startTime: number | undefined
-  ): SessionState | undefined {
-    const existing = sessions.get(event.sessionId);
+  function sessionState(sessionId: string): SessionState {
+    const existing = sessions.get(sessionId);
     if (existing !== undefined) {
       return existing;
     }
-    return openSession({
-      sessionId: event.sessionId,
-      session,
-      channelId: session.channelId,
-      startTime,
-      restored: true,
-    });
-  }
-
-  function openSession(args: {
-    sessionId: string;
-    session: SessionInfo;
-    channelId: string;
-    startTime: number | undefined;
-    restored: boolean;
-  }): SessionState {
-    const parent = context.active();
-    const span = runtime.tracer.startSpan(
-      "agent_sdk.session",
-      {
-        kind: SpanKind.INTERNAL,
-        startTime: args.startTime,
-        attributes: join(args.sessionId, {
-          "cursor.conversation.id": args.sessionId,
-          "agent_sdk.agent": agentName,
-          "agent_sdk.channel": args.channelId,
-          "agent_sdk.session_mode": args.session.mode,
-          "agent_sdk.session_purpose": args.session.purpose ?? "live",
-          "agent_sdk.session_restored": args.restored ? true : undefined,
-        }),
-      },
-      parent
-    );
-    const state: SessionState = {
-      span,
-      ctx: trace.setSpan(parent, span),
-      turns: new Map(),
-    };
-    sessions.set(args.sessionId, state);
-    if (!args.restored) {
-      metrics?.sessions.add(
-        1,
-        join(args.sessionId, {
-          "agent_sdk.agent": agentName,
-          "agent_sdk.channel": args.channelId,
-        })
-      );
-    }
+    const state: SessionState = { turns: new Map() };
+    sessions.set(sessionId, state);
     return state;
   }
 
@@ -652,10 +584,7 @@ export function createOtelCollector(
     if (event.turnId === undefined) {
       return undefined;
     }
-    const state = ensureSession(event, session, startTime);
-    if (state === undefined) {
-      return undefined;
-    }
+    const state = sessionState(event.sessionId);
     const existing = state.turns.get(event.turnId);
     if (existing !== undefined) {
       return existing;
@@ -688,10 +617,12 @@ export function createOtelCollector(
           "agent_sdk.agent": agentName,
           "agent_sdk.turn_id": args.turnId,
           "agent_sdk.channel": args.session.channelId,
+          "agent_sdk.session_mode": args.session.mode,
+          "agent_sdk.session_purpose": args.session.purpose ?? "live",
           "agent_sdk.turn_synthetic": args.synthetic ? true : undefined,
         }),
       },
-      args.state.ctx
+      ROOT_CONTEXT
     );
     const turn: TurnState = {
       span,
@@ -772,18 +703,10 @@ export function createOtelCollector(
     return span;
   }
 
-  function ensureCallSpan(args: OtelCallContext): Span {
+  function ensureTurnState(args: OtelTurnContext): TurnState {
     const startTime = Date.now();
-    const state =
-      sessions.get(args.sessionId) ??
-      openSession({
-        sessionId: args.sessionId,
-        session: args.session,
-        channelId: args.session.channelId,
-        startTime,
-        restored: true,
-      });
-    const turn =
+    const state = sessionState(args.sessionId);
+    return (
       state.turns.get(args.turnId) ??
       openTurn({
         state,
@@ -792,13 +715,22 @@ export function createOtelCollector(
         session: args.session,
         startTime,
         synthetic: true,
-      });
+      })
+    );
+  }
+
+  function ensureTurnSpan(args: OtelTurnContext): Span {
+    return ensureTurnState(args).span;
+  }
+
+  function ensureCallSpan(args: OtelCallContext): Span {
+    const turn = ensureTurnState(args);
     return openToolSpan({
       turn,
       sessionId: args.sessionId,
       turnId: args.turnId,
       call: { callId: args.callId, toolName: args.toolName },
-      startTime,
+      startTime: Date.now(),
     });
   }
 
@@ -825,15 +757,14 @@ export function createOtelCollector(
     }
     for (const turn of state.turns.values()) {
       endOpenChildren(turn, args.endTime);
+      if (args.message !== undefined) {
+        turn.span.setStatus({ code: args.code, message: args.message });
+      } else {
+        turn.span.setStatus({ code: args.code });
+      }
       turn.span.end(args.endTime);
     }
     state.turns.clear();
-    state.span.setStatus(
-      args.message === undefined
-        ? { code: args.code }
-        : { code: args.code, message: args.message }
-    );
-    state.span.end(args.endTime);
     sessions.delete(args.sessionId);
     extraBySession.delete(args.sessionId);
   }
@@ -846,7 +777,12 @@ export function createOtelCollector(
     sessionId: string,
     rest: Record<string, AttrValue | undefined>
   ): Record<string, AttrValue> {
-    return attrs({ ...extra(sessionId), ...rest });
+    return attrs({
+      ...extra(sessionId),
+      "cursor.conversation.id": sessionId,
+      "agent_sdk.session_id": sessionId,
+      ...rest,
+    });
   }
 
   function paintOpenSpans(
@@ -861,7 +797,6 @@ export function createOtelCollector(
     if (Object.keys(painted).length === 0) {
       return;
     }
-    state.span.setAttributes(painted);
     for (const turn of state.turns.values()) {
       turn.span.setAttributes(painted);
       for (const span of turn.tools.values()) {

package/src/internal/otel/config.ts

@@ -11,6 +11,7 @@ import type {
   OtelSignal,
   OtelTraceOptions,
 } from "../../otel.js";
+import { resolveOtelDefinition } from "../../otel.js";
 
 export interface ResolvedOtelConfig {
   enabled: boolean;
@@ -23,16 +24,6 @@ export interface ResolvedOtelConfig {
   logs: false | OtelLogOptions;
 }
 
-/** True when any standard OTLP endpoint env var is set. */
-export function hasOtelEnv(env: NodeJS.ProcessEnv = process.env): boolean {
-  return (
-    nonEmpty(env.OTEL_EXPORTER_OTLP_ENDPOINT) ||
-    nonEmpty(env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) ||
-    nonEmpty(env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT) ||
-    nonEmpty(env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT)
-  );
-}
-
 /**
  * Process-global authored config. OTel SDK is one per serve process — if
  * several mounts ship `agent/otel.ts`, they must be identical.
@@ -76,7 +67,8 @@ export function resolveOtelConfig(input: {
     return disabled();
   }
 
-  const authored = input.authored ?? {};
+  const authored =
+    input.authored === undefined ? {} : resolveOtelDefinition(input.authored);
   const serve = input.serve === undefined ? {} : input.serve;
   const merged: OtelConfig = {
     serviceName: serve.serviceName ?? authored.serviceName,
@@ -101,13 +93,17 @@ export function resolveOtelConfig(input: {
     input.authored !== undefined ||
     input.serve !== undefined ||
     envExporters.length > 0;
-  if (!optedIn || exporters.length === 0) {
+  if (!optedIn) {
     return disabled();
   }
 
   const traces = resolveSignal(merged.traces);
-  const metrics = resolveSignal(merged.metrics);
-  const logs = resolveLogs(merged.logs, env);
+  const metrics =
+    exporters.length === 0 ? false : resolveSignal(merged.metrics);
+  const logs = exporters.length === 0 ? false : resolveLogs(merged.logs, env);
+  if (exporters.length === 0 && traces === false) {
+    return disabled();
+  }
 
   return {
     enabled: traces !== false || metrics !== false || logs !== false,

package/src/internal/otel/http.ts

@@ -19,6 +19,16 @@ interface HttpSpanHandle {
   end(statusCode: number, error?: unknown): void;
 }
 
+const HTTP_SPAN_HANDLE_KEY = Symbol.for("anysphere.july.otel.httpSpanHandle");
+
+/** End the inbound SERVER span once the Fetch status is known (hosted flush). */
+export function endActiveHttpSpan(statusCode: number, error?: unknown): void {
+  const handle = context.active().getValue(HTTP_SPAN_HANDLE_KEY) as
+    | HttpSpanHandle
+    | undefined;
+  handle?.end(statusCode, error);
+}
+
 /**
  * Instrument one inbound Node request: SERVER span, W3C extract, auto-end
  * on response finish/close, run `fn` under the span context.
@@ -41,7 +51,10 @@ export function instrumentHttp<T>(
       handle.end(res.statusCode || 499);
     }
   });
-  return context.with(handle.context, fn);
+  return context.with(
+    handle.context.setValue(HTTP_SPAN_HANDLE_KEY, handle),
+    fn
+  );
 }
 
 function startHttpSpan(

package/src/internal/otel/mcp.ts

@@ -5,31 +5,18 @@
  */
 
 import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
-import { formatTraceparent, injectActiveTraceContext } from "../../otel.js";
+import { activeTraceparent, instrumentedFetch } from "../../otel.js";
 import { attrs } from "./attrs.js";
 
 const TRACER = "agent_sdk";
 
 export function instrumentedMcpFetch(base: typeof fetch = fetch): typeof fetch {
-  return (input, init) => {
-    if (input instanceof Request && init === undefined) {
-      const headers = new Headers(input.headers);
-      injectActiveTraceContext(headers);
-      return base(new Request(input, { headers }));
-    }
-    const headers = new Headers(init?.headers);
-    injectActiveTraceContext(headers);
-    return base(input, { ...init, headers });
-  };
+  return instrumentedFetch(base);
 }
 
 /** SEP-414 / OTel MCP carrier for `params._meta`. */
 export function mcpTraceMeta(): { traceparent: string } | undefined {
-  const span = trace.getSpan(context.active());
-  if (span === undefined) {
-    return undefined;
-  }
-  const traceparent = formatTraceparent(span.spanContext());
+  const traceparent = activeTraceparent();
   if (traceparent === undefined) {
     return undefined;
   }