@cursor/july 0.1.41 → 0.1.43

package/src/internal/server.ts

@@ -112,6 +112,10 @@ import {
   TOOL_MCP_ENDPOINT_PATH,
 } from "./mcp-endpoint.js";
 import { isLoopbackAddress } from "./net.js";
+import { createOtelCollector, type OtelCollector } from "./otel/collector.js";
+import { pickAuthoredOtel, resolveOtelConfig } from "./otel/config.js";
+import { instrumentHttp } from "./otel/http.js";
+import { createOtelRuntime, shutdownOtelRuntime } from "./otel/runtime.js";
 import { collectPeerConnections } from "./peer-connections.js";
 import {
   PLATFORM_SCHEDULE_CATALOG_FILENAME,
@@ -222,6 +226,30 @@ export async function startServer(
   // agentkit_enabled gate applies to every turn.
   process.env.CURSOR_AGENTKIT_VERSION ??= packageVersion();
 
+  const authoredOtel = pickAuthoredOtel(
+    mounts.map((m) => ({
+      slug: m.slug,
+      name: m.project.name,
+      otel: m.project.otel,
+    }))
+  );
+  const otelRuntime = createOtelRuntime(
+    resolveOtelConfig({
+      authored: authoredOtel,
+      serve: options.otel,
+    }),
+    logger
+  );
+  if (
+    otelRuntime === undefined &&
+    options.otel !== false &&
+    authoredOtel !== undefined
+  ) {
+    logger(
+      "[agent-sdk] otel: agent/otel.ts present but no OTLP exporters configured (set exporters or OTEL_EXPORTER_OTLP_ENDPOINT)"
+    );
+  }
+
   const cursorGithubTargets = collectCursorGithubTargets(mounts);
   const cursorGithubConfig = resolveCursorGithubEventConfig({
     configured: options.cursorEvents,
@@ -396,12 +424,17 @@ export async function startServer(
     const baseStateRoot =
       options.stateRoot ?? join(project.rootDir, ".agent-serve");
     const stateRoot = slug === "" ? baseStateRoot : join(baseStateRoot, slug);
+    const otelCollector: OtelCollector | undefined =
+      otelRuntime === undefined
+        ? undefined
+        : createOtelCollector(otelRuntime, project.name, logger);
     const engine = new SessionEngine({
       project,
       stateRoot,
       runner,
       logger,
       platforms: hostPlatforms,
+      otel: otelCollector,
     });
     // Rehydrate sessions from the authored storage sink before any
     // channel or route can address them (continuation tokens must resolve).
@@ -696,7 +729,9 @@ export async function startServer(
   });
 
   const server = createServer((req, res) => {
-    void handleRequest(router, req, res, logger);
+    void instrumentHttp(otelRuntime, req, res, () =>
+      handleRequest(router, req, res, logger)
+    );
   });
 
   const host = options.host ?? "127.0.0.1";
@@ -715,6 +750,7 @@ export async function startServer(
     await cursorEventRelay?.stop();
     await cursorSlackRelay?.stop();
     cursorGithubCredentials?.stop();
+    await shutdownOtelRuntime(otelRuntime);
     throw error;
   }
   const address = server.address() as AddressInfo;
@@ -900,6 +936,7 @@ export async function startServer(
         await Promise.all(runtimes.map((runtime) => runtime.engine.close()));
       } finally {
         cursorGithubCredentials?.stop();
+        await shutdownOtelRuntime(otelRuntime);
       }
     },
   };

package/src/internal/session-engine.ts

@@ -109,6 +109,7 @@ import {
 import { validateToolInput } from "./json-schema.js";
 import { LedgerServing, newLedgerPodId } from "./ledger-serving.js";
 import { McpHost } from "./mcp-host.js";
+import type { OtelCollector } from "./otel/collector.js";
 import {
   buildSessionContextBlock,
   SCHEDULE_CHANNEL_PREFIX,
@@ -243,6 +244,8 @@ export interface SessionEngineOptions {
    * *without* `cas` fails fast. Ignored for resident-mode agents.
    */
   durableSessionStore?: HostKvApi;
+  /** Process-level OTel collector; observe-only, never fatal. */
+  otel?: OtelCollector;
 }
 
 /**
@@ -358,6 +361,7 @@ export class SessionEngine {
   private readonly platforms: HostPlatforms;
   private readonly approvals = new ApprovalGate();
   private readonly abCollector: ABCollector;
+  private readonly otel: OtelCollector | undefined;
   private reminderApi: HostContext["reminders"];
   private evalsApi: HostContext["evals"];
   private readonly kvApi: HostContext["kv"];
@@ -390,6 +394,7 @@ export class SessionEngine {
     this.logger = options.logger ?? (() => {});
     this.getCloudUsage = options.getCloudUsage ?? defaultGetCloudUsage;
     this.estimateTurnCost = options.estimateTurnCost ?? estimateTurnCostFromApi;
+    this.otel = options.otel;
     this.turnGovernor = new TurnGovernor(options.project.agent.concurrency);
     this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
     this.nudgeStore = new SlackNudgeStore(
@@ -775,6 +780,17 @@ export class SessionEngine {
           cloudOverride: options.cloud,
         }));
       }
+      // Refresh wake-derived channel state (GitHub headSha / refs) without
+      // wiping sticky fields. Null patch values are skipped.
+      if (options.refreshState !== undefined) {
+        record = await this.updateRecord(record.sessionId, (current) => ({
+          ...current,
+          channelState: mergeChannelStateSkipNull(
+            current.channelState,
+            options.refreshState
+          ),
+        }));
+      }
       const coalesced = await this.startTurn(record.sessionId, message, {
         admission: options.admission ?? "preempt",
         ...(options.coalesceSourceTs === undefined
@@ -2436,6 +2452,7 @@ export class SessionEngine {
             },
             session: this.sessionInfo(record),
             stateRoot: this.stateRoot,
+            host: this.hostForSession(record.sessionId),
             artifacts: this.artifactsApi({
               sessionId: record.sessionId,
               turnId: event.turnId,
@@ -2456,6 +2473,8 @@ export class SessionEngine {
         this.project.name
       );
     }
+
+    this.otel?.onEvent(event, this.sessionInfo(record));
   }
 
   private channelEventHandlersFor(
@@ -3351,6 +3370,7 @@ export class SessionEngine {
     await this.storage?.close();
     await this.mcpHost.close();
     await this.runner.dispose?.();
+    this.otel?.close();
   }
 }
 
@@ -3384,6 +3404,38 @@ function mergePendingWorkspaceFiles(
   return { ...current, ...incoming };
 }
 
+/**
+ * Shallow-merge a wake patch into durable channel state. Null / undefined
+ * patch values leave the existing key alone so sticky fields survive.
+ */
+export function mergeChannelStateSkipNull(
+  current: JsonValue | undefined,
+  patch: JsonValue | undefined
+): JsonValue | undefined {
+  if (patch === undefined) {
+    return current;
+  }
+  if (
+    typeof patch !== "object" ||
+    patch === null ||
+    Array.isArray(patch) ||
+    typeof current !== "object" ||
+    current === null ||
+    Array.isArray(current)
+  ) {
+    return structuredClone(patch);
+  }
+  const merged: Record<string, JsonValue> = {
+    ...(current as Record<string, JsonValue>),
+  };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value !== null && value !== undefined) {
+      merged[key] = value as JsonValue;
+    }
+  }
+  return merged;
+}
+
 function eventsNdjson(events: SessionEvent[]): string | undefined {
   if (events.length === 0) {
     return undefined;

package/src/memory.ts

@@ -237,6 +237,10 @@ function truncate(text: string, max: number): string {
  * import { memoryHook } from "@cursor/july/memory";
  * export default memoryHook();
  * ```
+ *
+ * The journal is shared across every session — and every user — of the
+ * agent. Pass your own {@link MemoryHookOptions.backend} to change where
+ * memories live; delete the hook file to opt out entirely.
  */
 export function memoryHook(options: MemoryHookOptions = {}): HookDefinition {
   const backend = options.backend ?? defaultMemoryBackend();

package/src/otel.ts

@@ -0,0 +1,155 @@
+/**
+ * OpenTelemetry for Agent SDK — author `agent/otel.ts`, pass `serve({ otel })`,
+ * or set `OTEL_EXPORTER_OTLP_ENDPOINT` (standard OTel env).
+ *
+ * ```ts
+ * import { defineOtel } from "@cursor/july/otel";
+ *
+ * export default defineOtel({
+ *   serviceName: "cursor",
+ *   exporters: [{ url: "https://otel.example.com", protocol: "http/protobuf" }],
+ * });
+ * ```
+ */
+
+import { brandDefinition } from "./internal/brand.js";
+
+export type OtelSignal = "traces" | "metrics" | "logs";
+
+/** One OTLP destination. Multiple entries fan out. */
+export interface OtelExporterConfig {
+  /**
+   * OTLP base URL (`https://otel.example.com`) or signal path
+   * (`…/v1/traces`). Signal paths are stripped to the base; the runtime
+   * re-appends `/v1/{signal}`.
+   */
+  url: string;
+  /** Extra HTTP headers (merged with `OTEL_EXPORTER_OTLP_HEADERS`). */
+  headers?: Record<string, string>;
+  /**
+   * Wire format. Default `http/protobuf` (matches Cursor enterprise OTLP).
+   * Use `http/json` for collectors that only accept JSON.
+   */
+  protocol?: "http/json" | "http/protobuf";
+  /**
+   * Restrict this destination to these signals. Default: all enabled
+   * signals. Set by env when per-signal `OTEL_EXPORTER_OTLP_*_ENDPOINT`
+   * vars differ.
+   */
+  signals?: OtelSignal[];
+}
+
+export interface OtelTraceOptions {
+  /** Sample ratio in `[0, 1]`. Default `1`. */
+  sampleRatio?: number;
+}
+
+export interface OtelMetricOptions {
+  /** Export interval in ms. Default `10000`. */
+  exportIntervalMillis?: number;
+}
+
+export interface OtelLogOptions {
+  /**
+   * Include user prompt text on log records / span events.
+   * Default false; also toggled by `OTEL_LOG_USER_PROMPTS=1`.
+   */
+  userPrompts?: boolean;
+  /**
+   * Include tool argument / result payloads and failure text (truncated).
+   * Default false; also `OTEL_LOG_TOOL_CONTENT=1`.
+   */
+  toolContent?: boolean;
+}
+
+/**
+ * Authored / programmatic OTel config. Empty config still enables when
+ * standard `OTEL_EXPORTER_OTLP_*` env vars are set.
+ */
+export interface OtelConfig {
+  /**
+   * Resource `service.name`. Default: `OTEL_SERVICE_NAME` or `"cursor"`
+   * (same as enterprise export) so Agent SDK signals join org streams.
+   */
+  serviceName?: string;
+  /** Resource `service.version`. */
+  serviceVersion?: string;
+  /** Extra resource attributes on every signal. */
+  resourceAttributes?: Record<string, string>;
+  /**
+   * OTLP destinations. Default: from `OTEL_EXPORTER_OTLP_ENDPOINT` /
+   * per-signal `*_TRACES_ENDPOINT` etc. Empty with no env = disabled.
+   */
+  exporters?: OtelExporterConfig[];
+  /** Traces on/off or options. Default on. */
+  traces?: boolean | OtelTraceOptions;
+  /** Metrics on/off or options. Default on. */
+  metrics?: boolean | OtelMetricOptions;
+  /** Logs on/off or options. Default off (opt-in content). */
+  logs?: boolean | OtelLogOptions;
+}
+
+export type OtelDefinition = OtelConfig & { readonly __agentServe: "otel" };
+
+/** Author OpenTelemetry export under `agent/otel.ts`. */
+export function defineOtel(config: OtelConfig = {}): OtelDefinition {
+  if (config.exporters !== undefined) {
+    for (const exporter of config.exporters) {
+      if (typeof exporter.url !== "string" || exporter.url.length === 0) {
+        throw new Error(
+          "defineOtel: exporters[].url must be a non-empty string"
+        );
+      }
+      if (
+        exporter.protocol !== undefined &&
+        exporter.protocol !== "http/json" &&
+        exporter.protocol !== "http/protobuf"
+      ) {
+        throw new Error(
+          'defineOtel: exporters[].protocol must be "http/json" or "http/protobuf"'
+        );
+      }
+      assertSignals(exporter.signals);
+    }
+  }
+  if (config.resourceAttributes !== undefined) {
+    for (const [key, value] of Object.entries(config.resourceAttributes)) {
+      if (typeof value !== "string") {
+        throw new Error(
+          `defineOtel: resourceAttributes.${key} must be a string`
+        );
+      }
+    }
+  }
+  assertSampleRatio(config.traces);
+  return brandDefinition("otel", config);
+}
+
+function assertSignals(signals: OtelSignal[] | undefined): void {
+  if (signals === undefined) {
+    return;
+  }
+  if (signals.length === 0) {
+    throw new Error("defineOtel: exporters[].signals must be non-empty");
+  }
+  for (const signal of signals) {
+    if (signal !== "traces" && signal !== "metrics" && signal !== "logs") {
+      throw new Error(
+        'defineOtel: exporters[].signals must be "traces" | "metrics" | "logs"'
+      );
+    }
+  }
+}
+
+function assertSampleRatio(traces: OtelConfig["traces"]): void {
+  if (traces === undefined || typeof traces === "boolean") {
+    return;
+  }
+  const ratio = traces.sampleRatio;
+  if (ratio === undefined) {
+    return;
+  }
+  if (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {
+    throw new Error("defineOtel: traces.sampleRatio must be in [0, 1]");
+  }
+}

package/src/types.ts

@@ -11,6 +11,7 @@
 import type { InteractionUpdate, SDKCustomTool } from "@cursor/sdk";
 import type { z } from "zod";
 import type { ABConfigFile } from "./ab.js";
+import type { OtelConfig, OtelDefinition } from "./otel.js";
 import type { StorageDefinition } from "./storage.js";
 
 // ============================================================================
@@ -46,7 +47,8 @@ export type DefinitionKind =
   | "eval"
   | "ab"
   | "storage"
-  | "artifacts";
+  | "artifacts"
+  | "otel";
 
 export interface BrandedDefinition<K extends DefinitionKind> {
   readonly __agentServe: K;
@@ -455,9 +457,9 @@ export interface SlackNudgeHostApi {
 }
 
 /**
- * Shared host services available on every tool / channel / schedule surface.
- * Channel packs attach this as `ctx.host` so handlers can tap GitHub, Slack,
- * or MCP without the pack depending on another platform.
+ * Shared host services available on every tool / hook / channel / schedule
+ * surface. Channel packs attach this as `ctx.host` so handlers can tap
+ * GitHub, Slack, or MCP without the pack depending on another platform.
  */
 export interface HostContext {
   /**
@@ -1422,6 +1424,14 @@ export interface SendMessageOptions {
   continuationToken?: string;
   /** Initial channel state for newly created sessions. */
   state?: JsonValue;
+  /**
+   * On resume (continuation hit), shallow-merge into the existing session
+   * channel state before the turn starts. Null / undefined values in the
+   * patch do not overwrite existing keys, so sticky fields (stream ts,
+   * progress banner comment id, …) survive while wake-derived fields
+   * (`headSha`, refs) refresh. Ignored on create; pass {@link state} there.
+   */
+  refreshState?: JsonValue;
   /** Session display title (applied when creating a new session). */
   title?: string;
   /**
@@ -1891,6 +1901,12 @@ export interface HookContext {
    * memory journal) write here.
    */
   stateRoot: string;
+  /**
+   * Shared host services (MCP / GitHub / Slack / kv / files). Same as
+   * tool `ctx.host`. `files` is bound to this hook's session, so a
+   * relative path cannot read another session's files.
+   */
+  host: HostContext;
   /**
    * Durable artifacts, bound to this hook's session: `tag` auto-fills
    * `sessionId` (and `turnId` when known).
@@ -2368,6 +2384,8 @@ export interface AgentProject {
   storage?: StorageDefinition;
   /** Optional `agent/artifacts.ts` (`defineArtifacts`). */
   artifacts?: ArtifactsDefinition;
+  /** Optional `agent/otel.ts` (`defineOtel`). */
+  otel?: OtelDefinition;
   diagnostics: Diagnostic[];
 }
 
@@ -2450,6 +2468,7 @@ export interface AgentProjectInfo {
   };
   /** Project storage sink from `agent/storage.ts`, when authored. */
   storage?: { name?: string };
+  otel?: { serviceName?: string; enabled: true };
   /** Declared artifact kinds from `agent/artifacts.ts`, when authored. */
   artifacts?: { kinds: string[]; agentTool: boolean; max: number };
   diagnostics: Diagnostic[];
@@ -2640,6 +2659,12 @@ export interface ServeOptions {
     apiKey?: string;
   };
   logger?: (line: string) => void;
+  /**
+   * OpenTelemetry export. Pass a config object, or `false` to force-disable
+   * even when `OTEL_EXPORTER_OTLP_*` env vars / `agent/otel.ts` are set.
+   * When omitted, env + authored `defineOtel` still enable export.
+   */
+  otel?: OtelConfig | false;
 }
 
 /** One agent mounted on a server (its URL slug + compiled project). */

package/templates/triage/README.md

@@ -0,0 +1,48 @@
+# Triage agent
+
+A triage front door for your team. Send it bug reports, questions, and
+feedback; it classifies each report against a rubric, judges severity,
+records a structured verdict, and replies with the next step.
+
+Scaffolded with:
+
+```bash
+npx @cursor/july init ./my-triage-agent --template triage
+```
+
+## Run it
+
+```bash
+agent-sdk login   # once per machine
+agent-sdk dev
+```
+
+Open the playground URL it prints. Chat directly, or use the `/report`
+slash command to submit a report the way an integration would
+(`POST /v1/channels/intake/report`).
+
+## Wire it to Slack
+
+The Slack channel idles until its tokens exist. Create a Slack app and
+its env with:
+
+```bash
+agent-sdk slack setup
+```
+
+Then @mention the bot or DM it. The setup-slack skill in the
+@cursor/july package has the full walkthrough.
+
+## Make it yours
+
+- `agent/instructions.md` owns the flow every report follows.
+- `agent/skills/triage-rubric.md` owns the kinds, the tie-breakers, and
+  the severity ladder. Edit this first; it is the judgment.
+- `agent/tools/record_triage.ts` owns the verdict shape. Point its
+  `execute` at your tracker (Linear, GitHub Issues, a webhook) to file
+  real tickets.
+- `evals/triage.eval.ts` holds three smoke cases. Run `agent-sdk eval`
+  after every rubric change.
+
+The full walkthrough, from scaffold through deploy, is the triage
+cookbook: run `agent-sdk docs` and open Templates, then Triage agent.

package/templates/triage/agent/agent.ts

@@ -0,0 +1,14 @@
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  model: {
+    id: "grok-4.5",
+    params: [
+      { id: "effort", value: "high" },
+      { id: "fast", value: "true" },
+    ],
+  },
+  local: {
+    sandbox: true,
+  },
+});

package/templates/triage/agent/channels/intake.ts

@@ -0,0 +1,20 @@
+import { defineChannel, POST } from "@cursor/july/channels";
+import { z } from "zod";
+
+export default defineChannel({
+  routes: [
+    POST("/report", {
+      description: "Submit a report for triage",
+      bodySchema: z.object({
+        message: z.string(),
+        reporter: z.string().optional(),
+      }),
+      handler: async (_req, { send, body }) => {
+        const from =
+          body.reporter === undefined ? "" : ` (from ${body.reporter})`;
+        const session = await send(`New report${from}:\n\n${body.message}`);
+        return Response.json({ ok: true, sessionId: session.id });
+      },
+    }),
+  ],
+});

package/templates/triage/agent/channels/slack.ts

@@ -0,0 +1,3 @@
+import { slackChannel } from "@cursor/july/channels/slack";
+
+export default slackChannel();

package/templates/triage/agent/hooks/memory.ts

@@ -0,0 +1,3 @@
+import { memoryHook } from "@cursor/july/memory";
+
+export default memoryHook();

package/templates/triage/agent/instructions.md

@@ -0,0 +1,27 @@
+# Triage agent
+
+You are the triage front door for this team. People send you reports:
+bug reports, questions, feedback, feature ideas. You classify each one,
+judge its severity, and hand back a verdict the team can act on.
+
+Read the `triage-rubric` skill before classifying. It defines the three
+kinds and the tie-breakers.
+
+## Every report
+
+1. Read the report. If it is too thin to classify (no symptom, no
+   question, no opinion), ask for the missing piece once. Otherwise do
+   not ask; classify with what you have.
+2. If a `memory/` directory exists in your workspace, grep the journal
+   for similar past reports and say when one matches.
+3. Call `record_triage` exactly once with your verdict.
+4. Reply with the verdict: kind, severity, a one-line reason, and the
+   next step. Keep the reply under six lines. No preamble.
+
+## Boundaries
+
+- You classify and route. You do not fix bugs, write code, or promise
+  timelines.
+- When a report mixes kinds, pick the dominant one and name the split
+  in your reason.
+- Never invent reporter details. Missing fields stay empty.

package/templates/triage/agent/skills/triage-rubric.md

@@ -0,0 +1,43 @@
+---
+description: Definitions and tie-breakers for classifying a report as bug, question, or feedback, plus the severity ladder.
+---
+
+# Triage rubric
+
+## Kinds
+
+- **bug**: something is broken, erroring, slow, or behaving wrong right
+  now, and the reporter wants it diagnosed or fixed. Usually has a
+  symptom, an error, an id, a timestamp, or steps.
+- **question**: the reporter wants to know something that has an answer
+  (how does X work, is Y expected, who owns Z). Someone has to look it
+  up, not fix it.
+- **feedback**: an opinion, suggestion, complaint about how something
+  behaves, or a feature idea. The reporter is telling the team
+  something, not asking it to find anything out.
+
+## Tie-breakers
+
+- "This is annoying, you should change X" is feedback even when it
+  sounds like a complaint.
+- A question about a specific failure that already happened is a bug.
+  "Why did my export fail yesterday?" needs an investigation, not a
+  lookup.
+- A bug report that also suggests a fix is a bug.
+- A known bug with a workaround that only works sometimes is a bug. The
+  unreliable workaround is the thing to explain.
+- A feature idea phrased as a question ("could we have dark mode?") is
+  feedback.
+
+## Severity
+
+- **urgent**: data loss, security exposure, or many users blocked with
+  no workaround.
+- **high**: a core flow is broken or wrong for some users, no
+  reasonable workaround.
+- **medium**: broken or wrong with a workaround, or a sharp edge that
+  costs time.
+- **low**: cosmetic, minor friction, questions, and most feedback.
+
+Questions and feedback default to low unless the report shows real
+user impact.

package/templates/triage/agent/tools/record_triage.ts

@@ -0,0 +1,23 @@
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description:
+    "Record the structured triage verdict for the current report. Call exactly once per report, before replying.",
+  inputSchema: z.object({
+    kind: z.enum(["bug", "question", "feedback"]),
+    severity: z.enum(["low", "medium", "high", "urgent"]),
+    title: z
+      .string()
+      .max(80)
+      .describe("Short, imperative summary of the report."),
+    summary: z
+      .string()
+      .describe("What the reporter said, in two sentences or less."),
+    nextStep: z.string().describe("The single next action for the team."),
+    reporter: z.string().optional().describe("Who reported it, when known."),
+  }),
+  async execute(verdict) {
+    return { recorded: true, at: new Date().toISOString(), verdict };
+  },
+});

package/templates/triage/evals/evals.config.ts

@@ -0,0 +1,5 @@
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 10,
+});