@cursor/july 0.1.102 → 0.1.103

package/src/internal/otel/runtime.ts

@@ -10,6 +10,7 @@ import type { Histogram, Meter, Tracer } from "@opentelemetry/api";
 import { DiagLogLevel, diag, metrics, trace } from "@opentelemetry/api";
 import type { Logger as OtelLogger } from "@opentelemetry/api-logs";
 import { logs } from "@opentelemetry/api-logs";
+import { type ExportResult, ExportResultCode } from "@opentelemetry/core";
 import { OTLPLogExporter as OTLPLogExporterHttp } from "@opentelemetry/exporter-logs-otlp-http";
 import { OTLPLogExporter as OTLPLogExporterProto } from "@opentelemetry/exporter-logs-otlp-proto";
 import { OTLPMetricExporter as OTLPMetricExporterHttp } from "@opentelemetry/exporter-metrics-otlp-http";
@@ -29,6 +30,12 @@ import {
   MeterProvider,
   PeriodicExportingMetricReader,
 } from "@opentelemetry/sdk-metrics";
+import type {
+  ReadableSpan,
+  SpanExporter,
+  SpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import {
   BatchSpanProcessor,
   NodeTracerProvider,
@@ -39,28 +46,63 @@ import {
   ATTR_SERVICE_NAME,
   ATTR_SERVICE_VERSION,
 } from "@opentelemetry/semantic-conventions";
-import type { OtelExporterConfig, OtelSignal } from "../../otel.js";
+import {
+  installOutboundFetchInstrumentation,
+  type OtelExporterConfig,
+  type OtelSignal,
+} from "../../otel.js";
 import { exportersForSignal, type ResolvedOtelConfig } from "./config.js";
 import { ensureW3cPropagator } from "./propagation.js";
 
 const INSTRUMENTATION = "agent_sdk";
 
+/**
+ * Hosted v2 pods may be frozen or destroyed as soon as the HTTP reply
+ * lands. Bound the exporter wait so a slow collector cannot hold the
+ * delivery (OTLP BatchSpanProcessor defaults to 30s).
+ */
+export const OTEL_FORCE_FLUSH_TIMEOUT_MS = 1_000;
+
+/**
+ * First hosted OTLP POST may include a cold TLS handshake to Datadog.
+ * Bound separately from {@link OTEL_FORCE_FLUSH_TIMEOUT_MS} so the
+ * queued turn/tool batch is not abandoned after 1s.
+ */
+export const OTEL_DEFERRED_EXPORT_TIMEOUT_MS = 5_000;
+
+/** Drop oldest finished spans when no collector has drained the buffer. */
+export const OTEL_IN_MEMORY_SPAN_LIMIT = 2_048;
+
 export interface OtelRuntime {
   config: ResolvedOtelConfig;
   tracer: Tracer;
   meter: Meter | undefined;
   logger: OtelLogger | undefined;
   httpDuration: Histogram | undefined;
+  forceFlush: () => Promise<void>;
   shutdown: () => Promise<void>;
 }
 
+export interface CreateOtelRuntimeOptions {
+  /**
+   * Re-resolve exporters at flush (hosted v2 binds deployment secrets
+   * after bake). When bake had no OTLP exporters, finished spans sit
+   * in memory until this returns destinations.
+   */
+  resolveExport?: () => ResolvedOtelConfig;
+}
+
 export function createOtelRuntime(
   config: ResolvedOtelConfig,
-  log: (line: string) => void
+  log: (line: string) => void,
+  options?: CreateOtelRuntimeOptions
 ): OtelRuntime | undefined {
   if (!config.enabled) {
     return undefined;
   }
+  if (config.traces !== false) {
+    installOutboundFetchInstrumentation();
+  }
   const proto = process.env.OTEL_EXPORTER_OTLP_PROTOCOL?.trim().toLowerCase();
   if (proto === "grpc") {
     log(
@@ -68,7 +110,7 @@ export function createOtelRuntime(
     );
   }
   ensureW3cPropagator();
-  const sdk = startOtelSdk(config, log);
+  const sdk = startOtelSdk(config, log, options?.resolveExport);
   const meter =
     config.metrics === false
       ? undefined
@@ -85,20 +127,50 @@ export function createOtelRuntime(
             description: "HTTP request duration",
             unit: "ms",
           }),
+    forceFlush: sdk.forceFlush,
     shutdown: sdk.shutdown,
   };
 }
 
+export async function forceFlushOtelRuntime(
+  runtime: OtelRuntime | undefined
+): Promise<void> {
+  await runtime?.forceFlush();
+}
+
 export async function shutdownOtelRuntime(
   runtime: OtelRuntime | undefined
 ): Promise<void> {
   await runtime?.shutdown();
 }
 
+export async function raceOtelForceFlush(
+  work: Promise<unknown>,
+  log: (line: string) => void,
+  timeoutMs: number = OTEL_FORCE_FLUSH_TIMEOUT_MS
+): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<"timeout">((resolve) => {
+    timer = setTimeout(() => resolve("timeout"), timeoutMs);
+  });
+  const result = await Promise.race([
+    work.then(() => "done" as const).catch(() => "done" as const),
+    timeout,
+  ]);
+  if (timer !== undefined) {
+    clearTimeout(timer);
+  }
+  if (result === "timeout") {
+    log(`[agent-sdk:otel] forceFlush exceeded ${timeoutMs}ms; continuing`);
+  }
+}
+
 function startOtelSdk(
   config: ResolvedOtelConfig,
-  logger: (line: string) => void
+  logger: (line: string) => void,
+  resolveExport?: () => ResolvedOtelConfig
 ): {
+  forceFlush: () => Promise<void>;
   shutdown: () => Promise<void>;
 } {
   diag.setLogger(
@@ -116,30 +188,39 @@ function startOtelSdk(
   let tracerProvider: NodeTracerProvider | undefined;
   let meterProvider: MeterProvider | undefined;
   let loggerProvider: LoggerProvider | undefined;
+  let memoryExporter: BoundedMemorySpanExporter | undefined;
 
   const traceOpts = config.traces;
   if (traceOpts !== false) {
     const exporters = exportersForSignal(config.exporters, "traces");
-    if (exporters.length > 0) {
-      if (hasRealTracerProvider()) {
-        logger(
-          "[agent-sdk:otel] TracerProvider already registered; reusing global (Agent SDK OTLP exporters not attached)"
-        );
+    if (hasRealTracerProvider()) {
+      logger(
+        "[agent-sdk:otel] TracerProvider already registered; reusing global (Agent SDK OTLP exporters not attached)"
+      );
+    } else {
+      const spanProcessors: SpanProcessor[] = [];
+      if (exporters.length > 0) {
+        for (const exporter of exporters) {
+          spanProcessors.push(
+            new BatchSpanProcessor(
+              createTraceExporter(exporter, signalUrl(exporter.url, "traces"))
+            )
+          );
+        }
       } else {
-        tracerProvider = new NodeTracerProvider({
-          resource,
-          spanProcessors: exporters.map(
-            (exporter) =>
-              new BatchSpanProcessor(
-                createTraceExporter(exporter, signalUrl(exporter.url, "traces"))
-              )
-          ),
-          sampler: new ParentBasedSampler({
-            root: new TraceIdRatioBasedSampler(traceOpts.sampleRatio ?? 1),
-          }),
-        });
-        tracerProvider.register();
+        memoryExporter = new BoundedMemorySpanExporter(
+          OTEL_IN_MEMORY_SPAN_LIMIT
+        );
+        spanProcessors.push(new SimpleSpanProcessor(memoryExporter));
       }
+      tracerProvider = new NodeTracerProvider({
+        resource,
+        spanProcessors,
+        sampler: new ParentBasedSampler({
+          root: new TraceIdRatioBasedSampler(traceOpts.sampleRatio ?? 1),
+        }),
+      });
+      tracerProvider.register();
     }
   }
 
@@ -196,12 +277,63 @@ function startOtelSdk(
     }
   }
 
-  logger(
-    `[agent-sdk] otel enabled service=${config.serviceName} exporters=${config.exporters.length} traces=${config.traces !== false} metrics=${config.metrics !== false} logs=${config.logs !== false}`
-  );
+  if (memoryExporter === undefined) {
+    logger(
+      `[agent-sdk] otel enabled service=${config.serviceName} exporters=${config.exporters.length} traces=${config.traces !== false} metrics=${config.metrics !== false} logs=${config.logs !== false}`
+    );
+  } else {
+    logger(
+      `[agent-sdk] otel recording service=${config.serviceName} (export on flush when OTLP exporters resolve)`
+    );
+  }
+
+  const flushDeferred = async (): Promise<void> => {
+    if (memoryExporter === undefined) {
+      return;
+    }
+    const spans = memoryExporter.getFinishedSpans();
+    if (spans.length === 0) {
+      return;
+    }
+    const exportConfig = resolveExport?.() ?? config;
+    const destinations = exportersForSignal(exportConfig.exporters, "traces");
+    if (destinations.length === 0) {
+      return;
+    }
+    // Spans already carry the bake-time Resource. Hosted v2 binds
+    // deployment secrets after bake, so env / service extras on
+    // exportConfig must replace that Resource on the wire.
+    const ok = await exportQueuedSpans(
+      spans,
+      destinations,
+      logger,
+      buildResource(exportConfig)
+    );
+    if (ok) {
+      memoryExporter.reset();
+    }
+  };
 
   return {
+    forceFlush: async () => {
+      await Promise.allSettled([
+        raceOtelForceFlush(
+          Promise.allSettled([
+            tracerProvider?.forceFlush(),
+            meterProvider?.forceFlush(),
+            loggerProvider?.forceFlush(),
+          ]),
+          logger
+        ),
+        raceOtelForceFlush(
+          flushDeferred(),
+          logger,
+          OTEL_DEFERRED_EXPORT_TIMEOUT_MS
+        ),
+      ]);
+    },
     shutdown: async () => {
+      await flushDeferred();
       await Promise.allSettled([
         tracerProvider?.shutdown(),
         meterProvider?.shutdown(),
@@ -211,6 +343,54 @@ function startOtelSdk(
   };
 }
 
+function withExportResource(
+  span: ReadableSpan,
+  resource: Resource
+): ReadableSpan {
+  return new Proxy(span, {
+    get(target, prop, receiver) {
+      if (prop === "resource") {
+        return resource;
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  });
+}
+
+async function exportQueuedSpans(
+  spans: ReadableSpan[],
+  destinations: readonly OtelExporterConfig[],
+  logger: (line: string) => void,
+  resource: Resource
+): Promise<boolean> {
+  const payload = spans.map((span) => withExportResource(span, resource));
+  const exporters: SpanExporter[] = destinations.map((destination) =>
+    createTraceExporter(destination, signalUrl(destination.url, "traces"))
+  );
+  try {
+    const results = await Promise.all(
+      exporters.map(
+        (exporter) =>
+          new Promise<boolean>((resolve) => {
+            exporter.export(payload, (result: ExportResult) => {
+              resolve(result.code === ExportResultCode.SUCCESS);
+            });
+          })
+      )
+    );
+    return results.every((ok) => ok);
+  } catch (error) {
+    logger(
+      `[agent-sdk:otel] deferred export failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+    return false;
+  } finally {
+    await Promise.allSettled(exporters.map((exporter) => exporter.shutdown()));
+  }
+}
+
 function buildResource(config: ResolvedOtelConfig): Resource {
   // Align with Cursor enterprise wire resource attrs where they overlap so
   // Agent SDK traces join org metrics/logs in the same collector.
@@ -271,3 +451,38 @@ function createLogExporter(exporter: OtelExporterConfig, url: string) {
     ? new OTLPLogExporterProto(opts)
     : new OTLPLogExporterHttp(opts);
 }
+
+/** In-memory finished-span queue with a hard cap (oldest dropped). */
+class BoundedMemorySpanExporter implements SpanExporter {
+  private spans: ReadableSpan[] = [];
+
+  constructor(private readonly limit: number) {}
+
+  export(
+    spans: ReadableSpan[],
+    resultCallback: (result: ExportResult) => void
+  ): void {
+    this.spans.push(...spans);
+    if (this.spans.length > this.limit) {
+      this.spans.splice(0, this.spans.length - this.limit);
+    }
+    resultCallback({ code: ExportResultCode.SUCCESS });
+  }
+
+  getFinishedSpans(): ReadableSpan[] {
+    return this.spans.slice();
+  }
+
+  reset(): void {
+    this.spans = [];
+  }
+
+  shutdown(): Promise<void> {
+    this.reset();
+    return Promise.resolve();
+  }
+
+  forceFlush(): Promise<void> {
+    return Promise.resolve();
+  }
+}

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

@@ -18,12 +18,6 @@ import { toolInputJsonSchema, toolOutputJsonSchema } from "./json-schema.js";
 
 const require = createRequire(import.meta.url);
 
-const CONNECTION_SPECIFIERS = new Set([
-  "@anysphere/agent-serve/connections",
-  "@cursor/july/connections",
-  "@cursor/agentkit/connections",
-]);
-
 function sibling(basename: string): string {
   const dir = fileURLToPath(new URL(".", import.meta.url));
   const ts = join(dir, `${basename}.ts`);
@@ -94,12 +88,9 @@ serveInlineStdioMcp(
       {
         name: "inline-stdio-connection-stub",
         setup(build) {
-          build.onResolve({ filter: /.*/ }, (args) => {
-            if (CONNECTION_SPECIFIERS.has(args.path)) {
-              return { path: stubPath };
-            }
-            return undefined;
-          });
+          build.onResolve({ filter: /^@cursor\/july\/connections$/ }, () => ({
+            path: stubPath,
+          }));
         },
       },
     ],

package/src/internal/playground/toolchain.ts

@@ -16,7 +16,7 @@ import { playgroundBundleExists } from "./static.js";
 
 const VITE_CONFIG = "playground/vite.config.ts";
 
-/** `@anysphere/agent-serve` package root (works from `src/` or `dist/`). */
+/** Package root (works from `src/` or `dist/`). */
 export function packageRoot(): string {
   // src|dist/internal/playground/toolchain.ts → packages/agent-serve/
   return fileURLToPath(new URL("../../..", import.meta.url));

package/src/internal/request-error-status.ts

@@ -0,0 +1,72 @@
+import { InvalidAsOfError, VacuousTimeArgsError } from "./as-of.js";
+import { V2EngineError } from "./continuation-identity.js";
+import {
+  GUEST_CONNECT_STALLED,
+  GUEST_NETWORK_UNAVAILABLE,
+  GuestNetworkUnavailableError,
+  hasGuestNetworkErrno,
+  isQuietGuestConnectStall,
+} from "./guest-network.js";
+import { SessionAuthError, SessionBusyError } from "./session-engine.js";
+
+export interface MappedRequestError {
+  status: 400 | 403 | 409 | 503;
+  code: string;
+  message: string;
+}
+
+/**
+ * Expected throw → HTTP mapping used by `handleRequest` and hosted flush.
+ * Undefined means a real 500 (caller logs and redacts).
+ */
+export function mapThrownRequestError(
+  error: unknown
+): MappedRequestError | undefined {
+  if (error instanceof SessionBusyError) {
+    return { status: 409, code: "session_busy", message: error.message };
+  }
+  if (error instanceof V2EngineError) {
+    return {
+      status: 409,
+      code: "v2_identity_conflict",
+      message: "Control-plane session identity conflicts with existing state.",
+    };
+  }
+  if (error instanceof SessionAuthError) {
+    return { status: 403, code: "forbidden", message: error.message };
+  }
+  if (
+    error instanceof InvalidAsOfError ||
+    error instanceof VacuousTimeArgsError
+  ) {
+    return { status: 400, code: "invalid_request", message: error.message };
+  }
+  if (
+    error instanceof GuestNetworkUnavailableError ||
+    hasGuestNetworkErrno(error)
+  ) {
+    return {
+      status: 503,
+      code: GUEST_NETWORK_UNAVAILABLE,
+      message:
+        error instanceof Error
+          ? error.message
+          : "Guest network is not ready for outbound requests.",
+    };
+  }
+  if (isQuietGuestConnectStall(error)) {
+    return {
+      status: 503,
+      code: GUEST_CONNECT_STALLED,
+      message:
+        error instanceof Error
+          ? error.message
+          : "Guest Connect stalled without a network errno.",
+    };
+  }
+  return undefined;
+}
+
+export function statusForThrownRequestError(error: unknown): number {
+  return mapThrownRequestError(error)?.status ?? 500;
+}

package/src/internal/resolve-prod-target.ts

@@ -1,5 +1,5 @@
 /**
- * Resolve a hosted (managed) agent-serve deployment into a base URL +
+ * Resolve a hosted (managed) agent-sdk deployment into a base URL +
  * request headers for chat/run/call/eval `--prod`.
  *
  * Uses short-lived `engineAccess` from the deployment status route
@@ -16,6 +16,7 @@ import {
   validateDeploymentSlug,
 } from "./deploy-client.js";
 import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import { sleep as defaultSleep } from "./sleep.js";
 import { stderrPalette } from "./terminal-style.js";
 
 /**
@@ -98,7 +99,7 @@ export async function resolveProdTarget(
   // A hibernated engine can briefly omit engineAccess while getPod fails
   // during wake. Retry a few times before surfacing "not reachable yet".
   const maxReachabilityAttempts = 5;
-  const sleep = options.sleep ?? sleepMs;
+  const sleep = options.sleep ?? defaultSleep;
   let detail: DeploymentDetail | undefined;
   for (let attempt = 0; attempt < maxReachabilityAttempts; attempt++) {
     try {
@@ -250,12 +251,6 @@ function sanitizeCustomerFacingDetail(message: string): string {
     .replace(/\bcursorvm\.com\b/gi, "host");
 }
 
-function sleepMs(ms: number): Promise<void> {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
 /** Resolve the deployment slug the same way `deploy` does for a single dir. */
 export function resolveProdSlug(options: {
   dir: string;

package/src/internal/result-output.ts

@@ -0,0 +1,34 @@
+/**
+ * Run the authored `defineResult` commit on the final assistant text.
+ */
+
+import type { ResultContext, ResultDefinition } from "../types.js";
+
+export type ResultParse =
+  | { ok: true; text: string }
+  | { ok: false; message: string };
+
+export async function applyAuthoredResult(args: {
+  definition: ResultDefinition;
+  text: string | undefined;
+  dryRun: boolean;
+  ctx: Omit<ResultContext, "text">;
+}): Promise<ResultParse> {
+  if (args.text === undefined || args.text.trim() === "") {
+    return { ok: false, message: "turn produced no assistant text" };
+  }
+  const text = args.text;
+  if (args.dryRun) {
+    return { ok: true, text };
+  }
+  try {
+    await args.definition.commit({ ...args.ctx, text });
+  } catch (error) {
+    return {
+      ok: false,
+      message:
+        error instanceof Error ? error.message : `on commit: ${String(error)}`,
+    };
+  }
+  return { ok: true, text };
+}

package/src/internal/run-client.ts

@@ -1,7 +1,7 @@
 /**
- * Programmatic HTTP client for agent-serve sessions.
+ * Programmatic HTTP client for agent-sdk sessions.
  *
- * Used by `agent-serve run` and `chat --json`: create/follow a
+ * Used by `agent-sdk run` and `chat --json`: create/follow a
  * session, collect the NDJSON stream until the turn parks, and return a
  * compact {@link Trajectory} plus the continuation token for follow-ups.
  */

package/src/internal/runtime-dispatch-runner.ts

@@ -3,12 +3,9 @@
  * turns stay on the Cursor SDK runner, grokbot turns go to the Grok Bot
  * remote client (`internal/grokbot/runner.ts`), which drives the hosted
  * Grok Bot (Sand) harness through the public `/v0/grokbot` session API.
- * Both runners ship in the published package.
  */
 
 import type { RunnerTurnRequest, TurnOutcome } from "../types.js";
-import type { GrokBotRunnerOptions } from "./grokbot/runner.js";
-import { GrokBotRunner } from "./grokbot/runner.js";
 import type {
   AgentRunner,
   PrewarmOutcome,
@@ -18,30 +15,15 @@ import type {
 
 export interface RuntimeDispatchingRunnerOptions {
   sdkRunner: AgentRunner;
-  grokbot?: GrokBotRunnerOptions;
-  /** Test seam — replaces the real Grok Bot remote client. */
-  createGrokBotRunner?: (options: GrokBotRunnerOptions) => AgentRunner;
+  grokbot: AgentRunner;
 }
 
 export class RuntimeDispatchingRunner implements AgentRunner {
-  private grokbotRunner: AgentRunner | undefined;
-
   constructor(private readonly options: RuntimeDispatchingRunnerOptions) {}
 
-  /**
-   * The Grok Bot remote client, created on first use; a missing API key
-   * surfaces on the first grokbot turn, not at serve start.
-   */
-  ensureGrokBotRunner(): AgentRunner {
-    const options = this.options.grokbot ?? {};
-    this.grokbotRunner ??=
-      this.options.createGrokBotRunner?.(options) ?? new GrokBotRunner(options);
-    return this.grokbotRunner;
-  }
-
   async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
     if (request.runtime === "grokbot") {
-      return this.ensureGrokBotRunner().runTurn(request);
+      return this.options.grokbot.runTurn(request);
     }
     return this.options.sdkRunner.runTurn(request);
   }
@@ -68,6 +50,6 @@ export class RuntimeDispatchingRunner implements AgentRunner {
 
   async dispose(): Promise<void> {
     await this.options.sdkRunner.dispose?.();
-    await this.grokbotRunner?.dispose?.();
+    await this.options.grokbot.dispose?.();
   }
 }

package/src/internal/sdk-runner.ts

@@ -33,6 +33,8 @@ import { mapSdkTokenUsage, usageTokenSum } from "./cloud-turn-cost.js";
 import type { ConversationMirror } from "./conversation-mirror.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
 import { describeError } from "./describe-error.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import { sleep } from "./sleep.js";
 
 /** Mirrors @cursor/sdk's SteerAckOutcome; the published dist may predate it. */
 export type SteerAckOutcome = "complete_delivered" | "revert_to_followup";
@@ -496,7 +498,7 @@ export class CursorSdkRunner implements AgentRunner {
     const resolved = resolveApiKeySync({ apiKey: this.options.apiKey });
     if (resolved === undefined) {
       throw new Error(
-        "The Cursor SDK runner requires a Cursor credential: run `agent-serve login`, set CURSOR_API_KEY or CURSOR_API_KEY_FILE, or pass serve({ apiKey })."
+        `The Cursor SDK runner requires a Cursor credential: run \`${CLI} login\`, set CURSOR_API_KEY or CURSOR_API_KEY_FILE, or pass serve({ apiKey }).`
       );
     }
     return resolved.apiKey;
@@ -815,12 +817,6 @@ async function fillMissingCloudUsage(
   return outcome;
 }
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
 export function runErrorMessage(result: Pick<RunResult, "error">): string {
   return result.error?.message?.trim() || "The Cursor agent run failed";
 }