@cursor/july 0.1.109 → 0.1.112

package/src/internal/hosted-execution-latency.ts

@@ -0,0 +1,334 @@
+/**
+ * Hosted-execution interactive latency: first user-visible outbound and
+ * phase timings (send → waitForCompletion → durability drain → post-drain →
+ * total).
+ *
+ * Guest OTel (`agent_sdk.hosted_execution.*`) follows the package's existing
+ * guest-side OTel meter conventions (same pattern as `agent_sdk.http.duration`
+ * / process-memory histograms) so guest exporters can chart phases without
+ * waiting on control-plane scrape.
+ *
+ * Control-plane scrape of `as_hex` Server-Timing into
+ * `agent_sdk.runtime.hosted_execution.*` follows the established
+ * `guest_duration_ms` / `guest_network_wait_ms` path so Datadog control-plane
+ * dashboards can join execute wall time with guest phases. Both are retained
+ * because they feed different scrape surfaces already used in production.
+ *
+ * Tags stay low-cardinality: channel_kind, phase, outcome, delivery_surface.
+ * Never tag message content, Slack IDs, tokens, workflow/request/session IDs.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  type Attributes,
+  type Counter,
+  type Histogram,
+  type Meter,
+  metrics,
+} from "@opentelemetry/api";
+
+export const HOSTED_EXECUTION_DURATION_METRIC =
+  "agent_sdk.hosted_execution.duration_ms";
+export const HOSTED_EXECUTION_VISIBLE_REPLY_METRIC =
+  "agent_sdk.hosted_execution.visible_reply";
+
+/** Server-Timing metric name scraped by the control plane. */
+export const HOSTED_EXECUTION_SERVER_TIMING = "as_hex";
+
+export type HostedVisibleReplyOutcome =
+  | "none"
+  | "progress_update"
+  | "final_post"
+  | "error";
+
+export type HostedLatencyPhase =
+  | "to_first_visible"
+  | "first_visible_to_completion"
+  | "durability_drain"
+  | "post_drain"
+  | "total";
+
+export type HostedDeliverySurface = "slack" | "none";
+
+export type HostedExecutionLatencySnapshot = {
+  channelKind: string;
+  outcome: HostedVisibleReplyOutcome;
+  deliverySurface: HostedDeliverySurface;
+  phases: Partial<Record<HostedLatencyPhase, number>>;
+};
+
+type LatencyStore = {
+  startedAt: number;
+  channelKind: string;
+  firstVisibleAt: number | undefined;
+  firstVisibleOutcome:
+    | Exclude<HostedVisibleReplyOutcome, "none" | "error">
+    | undefined;
+  deliverySurface: HostedDeliverySurface;
+  visibleCounterEmitted: boolean;
+  errorEmitted: boolean;
+  finalized: boolean;
+};
+
+const latencyAls = new AsyncLocalStorage<LatencyStore>();
+
+const INSTRUMENTATION = "agent_sdk";
+
+let meterOverride: Meter | undefined;
+let durationHistogram: Histogram | undefined;
+let visibleCounter: Counter | undefined;
+let nowOverride: (() => number) | undefined;
+
+/** Monotonic clock used for latency marks (injectable in tests). */
+export function hostedExecutionNow(): number {
+  return nowOverride !== undefined ? nowOverride() : performance.now();
+}
+
+/** @internal */
+export function setHostedExecutionLatencyNowForTests(
+  now: (() => number) | undefined
+): void {
+  nowOverride = now;
+}
+
+/** @internal */
+export function setHostedExecutionLatencyMeterForTests(
+  meter: Meter | undefined
+): void {
+  meterOverride = meter;
+  durationHistogram = undefined;
+  visibleCounter = undefined;
+}
+
+/** @internal */
+export function resetHostedExecutionLatencyForTests(): void {
+  meterOverride = undefined;
+  durationHistogram = undefined;
+  visibleCounter = undefined;
+  nowOverride = undefined;
+}
+
+function resolveMeter(): Meter {
+  return meterOverride ?? metrics.getMeter(INSTRUMENTATION);
+}
+
+function durationInstrument(): Histogram {
+  if (durationHistogram === undefined) {
+    durationHistogram = resolveMeter().createHistogram(
+      HOSTED_EXECUTION_DURATION_METRIC,
+      {
+        unit: "ms",
+        description:
+          "Hosted execution interactive latency phases (first visible, completion, durability, post-drain, total)",
+      }
+    );
+  }
+  return durationHistogram;
+}
+
+function visibleInstrument(): Counter {
+  if (visibleCounter === undefined) {
+    visibleCounter = resolveMeter().createCounter(
+      HOSTED_EXECUTION_VISIBLE_REPLY_METRIC,
+      {
+        description:
+          "Hosted execution first-visible Slack outbound outcome (exact-once per execution)",
+      }
+    );
+  }
+  return visibleCounter;
+}
+
+export function sanitizeHostedChannelKind(value: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 64);
+  return normalized === "" ? "unknown" : normalized;
+}
+
+function baseAttrs(store: LatencyStore): Attributes {
+  return {
+    channel_kind: store.channelKind,
+    delivery_surface: store.deliverySurface,
+  };
+}
+
+/**
+ * Run hosted execution work inside the latency ALS. Slack delivery marks
+ * first-visible against this store; no-ops outside the window.
+ */
+export function runWithHostedExecutionLatency<T>(
+  args: { channelKind: string },
+  work: () => T
+): T {
+  const store: LatencyStore = {
+    startedAt: hostedExecutionNow(),
+    channelKind: sanitizeHostedChannelKind(args.channelKind),
+    firstVisibleAt: undefined,
+    firstVisibleOutcome: undefined,
+    deliverySurface: "none",
+    visibleCounterEmitted: false,
+    errorEmitted: false,
+    finalized: false,
+  };
+  return latencyAls.run(store, work);
+}
+
+export function isDuringHostedExecutionLatency(): boolean {
+  return latencyAls.getStore() !== undefined;
+}
+
+/**
+ * Mark the first user-visible Slack outbound success. Exact-once: later
+ * progress updates and final fallback posts are ignored.
+ */
+export function markHostedFirstVisibleReply(args: {
+  outcome: "progress_update" | "final_post";
+  deliverySurface?: HostedDeliverySurface;
+}): boolean {
+  const store = latencyAls.getStore();
+  if (store === undefined || store.firstVisibleAt !== undefined) {
+    return false;
+  }
+  store.firstVisibleAt = hostedExecutionNow();
+  store.firstVisibleOutcome = args.outcome;
+  store.deliverySurface = args.deliverySurface ?? "slack";
+  if (!store.visibleCounterEmitted) {
+    store.visibleCounterEmitted = true;
+    visibleInstrument().add(1, {
+      ...baseAttrs(store),
+      outcome: args.outcome,
+    });
+  }
+  return true;
+}
+
+/**
+ * Count a visible-outbound failure when nothing user-visible succeeded yet.
+ * Exact-once; ignored after a first-visible mark or a prior error.
+ */
+export function noteHostedVisibleReplyError(args?: {
+  deliverySurface?: HostedDeliverySurface;
+}): void {
+  const store = latencyAls.getStore();
+  if (
+    store === undefined ||
+    store.errorEmitted ||
+    store.firstVisibleAt !== undefined
+  ) {
+    return;
+  }
+  store.errorEmitted = true;
+  if (args?.deliverySurface !== undefined) {
+    store.deliverySurface = args.deliverySurface;
+  } else if (store.deliverySurface === "none") {
+    store.deliverySurface = "slack";
+  }
+  if (!store.visibleCounterEmitted) {
+    store.visibleCounterEmitted = true;
+    visibleInstrument().add(1, {
+      ...baseAttrs(store),
+      outcome: "error",
+    });
+  }
+}
+
+function resolveOutcome(store: LatencyStore): HostedVisibleReplyOutcome {
+  if (store.firstVisibleOutcome !== undefined) {
+    return store.firstVisibleOutcome;
+  }
+  if (store.errorEmitted) {
+    return "error";
+  }
+  return "none";
+}
+
+/**
+ * Emit phase histograms + optional none counter; return a snapshot for
+ * Server-Timing. Safe to call once per ALS window.
+ *
+ * `endedAt` should be taken as late as possible before the execution reply
+ * (or rethrow) is returned so `total` and `post_drain` include eviction and
+ * diagnostic write work after durability drain.
+ */
+export function finalizeHostedExecutionLatency(marks: {
+  completionAt: number;
+  drainAt: number;
+  endedAt: number;
+}): HostedExecutionLatencySnapshot | undefined {
+  const store = latencyAls.getStore();
+  if (store === undefined || store.finalized) {
+    return undefined;
+  }
+  store.finalized = true;
+
+  const outcome = resolveOutcome(store);
+  if (!store.visibleCounterEmitted) {
+    store.visibleCounterEmitted = true;
+    visibleInstrument().add(1, {
+      ...baseAttrs(store),
+      outcome: "none",
+    });
+  }
+
+  const phases: Partial<Record<HostedLatencyPhase, number>> = {
+    durability_drain: Math.max(0, marks.drainAt - marks.completionAt),
+    post_drain: Math.max(0, marks.endedAt - marks.drainAt),
+    total: Math.max(0, marks.endedAt - store.startedAt),
+  };
+  if (store.firstVisibleAt !== undefined) {
+    phases.to_first_visible = Math.max(
+      0,
+      store.firstVisibleAt - store.startedAt
+    );
+    phases.first_visible_to_completion = Math.max(
+      0,
+      marks.completionAt - store.firstVisibleAt
+    );
+  }
+
+  const attrs: Attributes = {
+    channel_kind: store.channelKind,
+    outcome,
+    delivery_surface: store.deliverySurface,
+  };
+  const histogram = durationInstrument();
+  for (const [phase, value] of Object.entries(phases) as Array<
+    [HostedLatencyPhase, number]
+  >) {
+    histogram.record(value, { ...attrs, phase });
+  }
+
+  return {
+    channelKind: store.channelKind,
+    outcome,
+    deliverySurface: store.deliverySurface,
+    phases,
+  };
+}
+
+export function formatHostedExecutionLatencyServerTiming(
+  snapshot: HostedExecutionLatencySnapshot
+): string[] {
+  const parts: string[] = [];
+  const order: HostedLatencyPhase[] = [
+    "to_first_visible",
+    "first_visible_to_completion",
+    "durability_drain",
+    "post_drain",
+    "total",
+  ];
+  for (const phase of order) {
+    const dur = snapshot.phases[phase];
+    if (dur === undefined) {
+      continue;
+    }
+    parts.push(
+      `${HOSTED_EXECUTION_SERVER_TIMING};desc="${phase}";dur=${Math.max(0, dur).toFixed(1)};outcome="${snapshot.outcome}";ch="${snapshot.channelKind}";sf="${snapshot.deliverySurface}"`
+    );
+  }
+  return parts;
+}

package/src/internal/hosting.ts

@@ -19,13 +19,12 @@ export const MAX_SECRET_NAME_LENGTH = 64;
 export const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
 
 /**
- * Additional platform-managed env names for Cursor-hosted durable storage
- * (Bugbot `agent_serve_*`). Mirrored from
- * `@cursor/july/storage/cursor-hosted` so validate/secrets CLI stay in sync
- * without importing the storage backend into the CLI graph.
+ * Extra platform-managed env names (not `CURSOR_*`). Mirrored from
+ * `@cursor/july/internal/cursor-hosted` so validate/secrets CLI stay in
+ * sync without importing the storage backend into the CLI graph.
+ * Hosted storage is HTTP-proxied; engines never see a database URL.
  */
 export const PLATFORM_HOSTED_STORAGE_SECRET_NAMES = [
-  "BUGBOTDB_URL",
   "AGENT_SERVE_DEPLOYMENT_ID",
 ] as const;
 
@@ -70,7 +69,7 @@ export function isReservedSecretName(name: string): boolean {
   }
   const upper = name.toUpperCase();
   return (PLATFORM_HOSTED_STORAGE_SECRET_NAMES as readonly string[]).some(
-    (managed) => managed === upper
+    managed => managed === upper
   );
 }
 

package/src/internal/http-channel-define.ts

@@ -0,0 +1,27 @@
+/**
+ * Constructor for the built-in HTTP session channel. The runtime always
+ * mounts this channel; authors use `defineChannel` for custom surfaces.
+ */
+
+import type { HttpChannelConfig, HttpChannelDefinition } from "../types.js";
+import { brandDefinition } from "./brand.js";
+import { normalizeIdentity } from "./continuation-identity.js";
+import { attachHttpControlPlaneAdmission } from "./http-control-plane-session.js";
+
+/**
+ * Configure the built-in HTTP session channel. Used by discovery as the
+ * default (and for an optional internal `agent/channels/http.ts` override).
+ */
+export function httpChannel(
+  config: HttpChannelConfig = {}
+): HttpChannelDefinition {
+  const definition =
+    config.continuation !== undefined
+      ? brandDefinition("http-channel", {
+          ...config,
+          continuation: normalizeIdentity(config.continuation, "http"),
+        })
+      : brandDefinition("http-channel", config);
+  attachHttpControlPlaneAdmission(definition);
+  return definition;
+}

package/src/internal/http-channel.ts

@@ -1,8 +1,7 @@
 /**
  * The built-in HTTP session channel: the default API that `curl`, SDK
- * clients, and frontends talk to. Mounted at `/v1/session*` and enabled even
- * when `agent/channels/http.ts` does not exist; author that file with
- * `httpChannel({ ... })` to override auth or observe events.
+ * clients, and frontends talk to. Mounted at `/v1/session*` even when no
+ * channel override is present.
  *
  * Continuation semantics: `POST /v1/session` returns a `continuationToken`;
  * each accepted follow-up rotates it and returns the replacement, and a
@@ -294,7 +293,7 @@ export function buildHttpChannelRoutes(args: {
           playgroundUrl: playgroundUrlForSession(request, base, sessionId),
         });
       }
-      const ndjson = `${snapshot.map((e) => JSON.stringify(e)).join("\n")}${
+      const ndjson = `${snapshot.map(e => JSON.stringify(e)).join("\n")}${
         snapshot.length > 0 ? "\n" : ""
       }`;
       return new Response(ndjson, {

package/src/internal/http-control-plane-session.ts

@@ -3,9 +3,11 @@
  *
  * `agent-sdk run --prod` reaches the authenticated CP start route, which
  * delivers `agentsdk.session` to the built-in `http` channel of every v2
- * agent. The wake is `send(message, { dryRun, asOf })`; the session id, when
- * the caller resumed an explicit `ses_…`, arrives through the hosted
- * execution (never through this payload), so authored code cannot pick one.
+ * agent. The wake is `send(message, { dryRun, asOf })`; the session id,
+ * when the caller resumed an explicit `ses_…`, arrives through the hosted
+ * execution (never through this payload), so authored code cannot pick
+ * one. {@link HttpChannelDefinition.onAdmit} runs against the mailbox
+ * key and the original message before that send is captured.
  */
 
 import type { ChannelHandlerArgs, HttpChannelDefinition } from "../types.js";
@@ -15,6 +17,7 @@ import {
   AGENT_SDK_HTTP_CHANNEL_KIND,
   AGENT_SDK_SESSION_EVENT_TYPE,
 } from "./hosted-catch-protocol.js";
+import { isRecord } from "./is-record.js";
 
 export type ControlPlaneSessionPayload = {
   message: string;
@@ -25,10 +28,6 @@ export type ControlPlaneSessionPayload = {
 const PAYLOAD_KEYS = new Set(["message", "dryRun", "asOf"]);
 const MAX_MESSAGE_CHARS = 64 * 1024;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 export function parseControlPlaneSessionPayload(
   payload: unknown
 ):
@@ -37,7 +36,7 @@ export function parseControlPlaneSessionPayload(
   if (!isRecord(payload)) {
     return { ok: false, error: "payload must be an object" };
   }
-  if (Object.keys(payload).some((key) => !PAYLOAD_KEYS.has(key))) {
+  if (Object.keys(payload).some(key => !PAYLOAD_KEYS.has(key))) {
     return { ok: false, error: "payload carries an unsupported field" };
   }
   const message =
@@ -68,7 +67,9 @@ export async function dispatchHttpControlPlaneSession(input: {
   eventType: string;
   payload: unknown;
   args: ChannelHandlerArgs;
+  mailboxContinuationKey: string;
   onMessage?: HttpChannelDefinition["onMessage"];
+  onAdmit?: HttpChannelDefinition["onAdmit"];
 }): Promise<Response> {
   if (input.eventType !== AGENT_SDK_SESSION_EVENT_TYPE) {
     return skipped("not a control-plane session");
@@ -77,10 +78,20 @@ export async function dispatchHttpControlPlaneSession(input: {
   if (!parsed.ok) {
     return Response.json({ ok: false, error: parsed.error }, { status: 400 });
   }
+  const original = parsed.data.message;
+  if (input.onAdmit !== undefined) {
+    await input.onAdmit({
+      message: original,
+      sessionKey: input.mailboxContinuationKey,
+      dryRun: parsed.data.dryRun,
+      asOf: parsed.data.asOf,
+      host: input.args.host,
+    });
+  }
   const message =
     input.onMessage === undefined
-      ? parsed.data.message
-      : await input.onMessage(parsed.data.message, { auth: null });
+      ? original
+      : await input.onMessage(original, { auth: null });
   const session = await input.args.send(message, {
     dryRun: parsed.data.dryRun,
     asOf: parsed.data.asOf,
@@ -93,12 +104,14 @@ export function attachHttpControlPlaneAdmission(
 ): void {
   attachHostedAdmissionAdapter(definition, {
     kind: AGENT_SDK_HTTP_CHANNEL_KIND,
-    dispatch: ({ eventType, payload, args }) =>
+    dispatch: ({ eventType, payload, args, mailboxContinuationKey }) =>
       dispatchHttpControlPlaneSession({
         eventType,
         payload,
         args,
+        mailboxContinuationKey: mailboxContinuationKey ?? "",
         onMessage: definition.onMessage,
+        onAdmit: definition.onAdmit,
       }),
   });
 }

package/src/internal/incoming-headers-to-fetch.ts

@@ -0,0 +1,54 @@
+import type { IncomingHttpHeaders } from "node:http";
+
+/**
+ * Fetch / RFC 9110 header-name token. HTTP/2 pseudo-headers (`:method`,
+ * `:path`, `:authority`, `:scheme`) fail this and throw in `Headers.append`.
+ */
+const FETCH_HEADER_NAME = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/;
+
+function isFetchHeaderName(name: string): boolean {
+  return FETCH_HEADER_NAME.test(name);
+}
+
+/**
+ * Copy Node incoming headers into a Fetch `Headers` object, dropping names
+ * the Fetch API rejects (HTTP/2 pseudo-headers and any other illegal token).
+ * Real headers are unchanged.
+ */
+export function incomingHeadersToFetch(headers: IncomingHttpHeaders): Headers {
+  const out = new Headers();
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === undefined || !isFetchHeaderName(key)) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        out.append(key, item);
+      }
+    } else {
+      out.set(key, value);
+    }
+  }
+  return out;
+}
+
+function firstHeaderValue(
+  value: string | string[] | undefined
+): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  return Array.isArray(value) ? value[0] : value;
+}
+
+/** HTTP/1 `Host`, or HTTP/2 `:authority` when Host was not copied. */
+export function incomingRequestHost(
+  headers: IncomingHttpHeaders,
+  fallback = "127.0.0.1"
+): string {
+  return (
+    firstHeaderValue(headers.host) ??
+    firstHeaderValue(headers[":authority"]) ??
+    fallback
+  );
+}

package/src/internal/init-interview.ts

@@ -56,7 +56,7 @@ export function templateFileHasReplacements(
   rel: string
 ): boolean {
   const file = posixRel(rel);
-  return spec.replace.some((rule) => posixRel(rule.file) === file);
+  return spec.replace.some(rule => posixRel(rule.file) === file);
 }
 
 export async function loadTemplateInitSpec(
@@ -168,7 +168,7 @@ export async function collectTemplateAnswers(
   const vars = input.vars ?? {};
   const answers: Record<string, string> = {};
   const ask = input.ask ?? promptTemplateQuestion;
-  const out = input.out ?? ((text) => process.stdout.write(text));
+  const out = input.out ?? (text => process.stdout.write(text));
 
   for (const question of input.spec.questions) {
     if (question.id in vars) {
@@ -241,7 +241,7 @@ export async function promptTemplateQuestion(
     if (question.hint !== undefined) {
       output.write(`  ${question.hint}\n`);
     }
-    return await new Promise<string>((resolve) => {
+    return await new Promise<string>(resolve => {
       rl.question(`${question.prompt}${suffix} `, resolve);
     });
   } finally {
@@ -286,7 +286,7 @@ function parseQuestionValue(
   if (question.parse === "owner-repo-list") {
     try {
       const scope = parseCursorGithubRepoScope(
-        trimmed.split(",").map((repo) => repo.trim())
+        trimmed.split(",").map(repo => repo.trim())
       );
       return { ok: true, value: scope.repos.join(", ") };
     } catch (error) {
@@ -304,10 +304,10 @@ function formatReplaceValue(
   if (raw === undefined || raw === "") {
     return undefined;
   }
-  const parts = raw.split(",").map((part) => part.trim());
+  const parts = raw.split(",").map(part => part.trim());
   let value = raw;
   if (rule.as === "json-array") {
-    value = `[${parts.map((part) => JSON.stringify(part)).join(", ")}]`;
+    value = `[${parts.map(part => JSON.stringify(part)).join(", ")}]`;
   } else if (rule.as === "first") {
     const first = parts[0];
     if (first === undefined || first === "") {
@@ -344,7 +344,7 @@ function parseQuestion(value: unknown, index: number): TemplateQuestion {
     question.default = value.default;
   }
   if (Array.isArray(value.choices)) {
-    question.choices = value.choices.map((choice) => String(choice));
+    question.choices = value.choices.map(choice => String(choice));
   }
   if (value.parse === "owner-repo-list") {
     question.parse = "owner-repo-list";