@cursor/july 0.1.42 → 0.1.45

package/src/internal/sdk-runner.ts

@@ -52,6 +52,7 @@ export type RunnerPrewarmRequest = Pick<
   | "workspaceDir"
   | "runnerStateDir"
   | "sandbox"
+  | "tools"
   | "mcpServers"
   | "subagents"
   | "model"
@@ -373,6 +374,11 @@ export class CursorSdkRunner implements AgentRunner {
       this.options.store ?? (await this.getStore(request.runnerStateDir));
     return {
       ...this.buildSharedOptions(request),
+      // The built-in tool allowlist rides AgentOptions, not `local`, and is
+      // deliberately absent from openCloudAgent's options: the SDK rejects
+      // tool restrictions on cloud agents. Passed on create *and* resume
+      // (both flow through here) — the SDK does not persist it across runs.
+      ...(request.tools === undefined ? {} : { tools: request.tools }),
       local: {
         cwd: request.workspaceDir,
         settingSources: ["project"],

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,18 @@ 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,
+      otelMeter: otelRuntime?.meter,
     });
     // Rehydrate sessions from the authored storage sink before any
     // channel or route can address them (continuation tokens must resolve).
@@ -696,7 +730,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 +751,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 +937,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

@@ -10,6 +10,7 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { SDKCustomTool, SDKCustomToolResult } from "@cursor/sdk";
+import type { Meter } from "@opentelemetry/api";
 import {
   type ABDefinition,
   mergeABInstructions,
@@ -95,6 +96,7 @@ import { TurnEventMapper } from "./event-mapper.js";
 import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
 import { createHostFilesApi } from "./host-files.js";
 import { createHostKvApi } from "./host-kv.js";
+import { createHostOtelApi, type HostOtelSessionApi } from "./host-otel.js";
 import {
   createHostPlatforms,
   createHostSlackClient,
@@ -109,6 +111,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 +246,10 @@ export interface SessionEngineOptions {
    * *without* `cas` fails fast. Ignored for resident-mode agents.
    */
   durableSessionStore?: HostKvApi;
+  /** Process-level OTel collector; observe-only, never fatal. */
+  otel?: OtelCollector;
+  /** Process-level meter for {@link HostContext.otel}. Absent → no-op counters. */
+  otelMeter?: Meter;
 }
 
 /**
@@ -358,6 +365,8 @@ export class SessionEngine {
   private readonly platforms: HostPlatforms;
   private readonly approvals = new ApprovalGate();
   private readonly abCollector: ABCollector;
+  private readonly otel: OtelCollector | undefined;
+  private readonly otelHost: HostOtelSessionApi;
   private reminderApi: HostContext["reminders"];
   private evalsApi: HostContext["evals"];
   private readonly kvApi: HostContext["kv"];
@@ -390,6 +399,12 @@ export class SessionEngine {
     this.logger = options.logger ?? (() => {});
     this.getCloudUsage = options.getCloudUsage ?? defaultGetCloudUsage;
     this.estimateTurnCost = options.estimateTurnCost ?? estimateTurnCostFromApi;
+    this.otel = options.otel;
+    this.otelHost = createHostOtelApi({
+      agentName: options.project.name,
+      meter: options.otelMeter,
+      collector: options.otel,
+    });
     this.turnGovernor = new TurnGovernor(options.project.agent.concurrency);
     this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
     this.nudgeStore = new SlackNudgeStore(
@@ -569,7 +584,7 @@ export class SessionEngine {
     this.cloudServerToolsConnection = connection;
   }
 
-  /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / Slack nudges). */
+  /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / files / otel / Slack nudges). */
   get host(): HostContext {
     return {
       mcp: this.mcpHost,
@@ -579,6 +594,7 @@ export class SessionEngine {
       evals: this.evalsApi,
       kv: this.kvApi,
       files: this.filesApi,
+      otel: this.otelHost,
       slackNudges: this.slackNudgeHostApi(),
     };
   }
@@ -593,7 +609,11 @@ export class SessionEngine {
     const host = this.host;
     return sessionId === undefined
       ? host
-      : { ...host, files: this.filesApi.forSession(sessionId) };
+      : {
+          ...host,
+          files: this.filesApi.forSession(sessionId),
+          otel: this.otelHost.forSession(sessionId),
+        };
   }
 
   /** Unbound `ctx.artifacts` facade (channel handlers, scratch tool calls). */
@@ -775,6 +795,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
@@ -1343,6 +1374,9 @@ export class SessionEngine {
         workspaceDir,
         runnerStateDir: join(this.stateRoot, "runner"),
         sandbox: agent.local?.sandbox === true,
+        ...(agent.allowedTools === undefined
+          ? {}
+          : { tools: agent.allowedTools }),
         mcpServers: this.buildMcpServers("local"),
         subagents: buildRunnerSubagents(agent),
         ...(agent.model === undefined ? {} : { model: agent.model }),
@@ -1598,6 +1632,15 @@ export class SessionEngine {
       agentRuntime: agent.runtime,
       cloudOverride: record.cloudOverride,
     });
+    // Fail closed: the SDK cannot enforce the built-in tool allowlist on
+    // cloud agents yet, and a restriction that silently does not apply is
+    // worse than a refused turn. Cloud-runtime agents already fail
+    // discovery; this guards hybrid agents' per-send cloud sessions.
+    if (runtime === "cloud" && agent.allowedTools !== undefined) {
+      throw new Error(
+        `Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on cloud turns yet. Refusing the cloud session rather than running it unrestricted.`
+      );
+    }
     const mergedCloud =
       runtime === "cloud"
         ? mergeCloudOptions({
@@ -1652,6 +1695,9 @@ export class SessionEngine {
         : { sdkAgentId: record.sdkAgentId }),
       workspaceDir: this.harnessCwd(record),
       sandbox: this.project.agent.local?.sandbox === true,
+      ...(runtime === "local" && agent.allowedTools !== undefined
+        ? { tools: agent.allowedTools }
+        : {}),
       runnerStateDir: join(this.stateRoot, "runner"),
       prompt: turnPrompt,
       isFirstTurn,
@@ -2457,6 +2503,8 @@ export class SessionEngine {
         this.project.name
       );
     }
+
+    this.otel?.onEvent(event, this.sessionInfo(record));
   }
 
   private channelEventHandlersFor(
@@ -3352,6 +3400,7 @@ export class SessionEngine {
     await this.storage?.close();
     await this.mcpHost.close();
     await this.runner.dispose?.();
+    this.otel?.close();
   }
 }
 
@@ -3385,6 +3434,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

@@ -8,9 +8,10 @@
  * SDK as the execution harness.
  */
 
-import type { InteractionUpdate, SDKCustomTool } from "@cursor/sdk";
+import type { InteractionUpdate, SDKCustomTool, ToolName } 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;
@@ -204,6 +206,40 @@ export interface AgentConfig {
    * {@link BuiltinToolsConfig}.
    */
   builtinTools?: BuiltinToolsConfig;
+  /**
+   * Allowlist of built-in harness tools offered to the model
+   * (`AgentOptions.tools` on the SDK). Opt-in by design: unset keeps the
+   * model's full standard toolset, and once set the agent gets exactly
+   * what it names — nothing more, `[]` meaning no native built-in tools.
+   * There is deliberately no exclusion form: an agent that restricts
+   * tools states what it keeps, so tools the platform adds later stay
+   * off until someone opts in.
+   *
+   * `"mcp"` is always granted alongside a configured allowlist. It is
+   * transport, not capability: this kit's own server tools reach the
+   * model over the SDK custom-tool MCP path, so omitting it would
+   * silently strand `agent/tools/`. What MCP actually exposes stays
+   * governed by the second layer — the tools you author, the connections
+   * you declare, and the harness cwd's ambient `.cursor` config (point
+   * `local.cwd` outside checkouts whose MCP servers the agent must not
+   * see, and `local.sandbox` makes MCP calls fail closed).
+   *
+   * Names use the SDK's public tool vocabulary (`"shell"`, `"read"`,
+   * `"edit"`, `"grep"`, `"glob"`, `"ls"`, `"task"`, ...). `"shell"` is a
+   * capability group that also grants shell stdin writes — and is what
+   * `execution: "agent"` tool scripts run through, so an allowlist
+   * without it strands them (discovery warns). `"task"` gates subagents.
+   * Unknown names fail the turn (`ConfigurationError` at `Agent.create`).
+   *
+   * The allowlist states runtime-agnostic intent, but the SDK cannot
+   * enforce tool restrictions on cloud agents yet, and it must never
+   * silently not apply: a `runtime: "cloud"` agent that sets it fails at
+   * serve start (error diagnostic), and a hybrid agent's per-send cloud
+   * sessions are refused (the turn errors) rather than run unrestricted.
+   * Not a security boundary against the serve host: like `local.sandbox`,
+   * it only shapes what the model can call.
+   */
+  tools?: ToolName[];
   /**
    * How the serve host coordinates event delivery and turn execution. See
    * {@link AgentServingMode}. Defaults to `"resident"`; opt in to
@@ -504,6 +540,12 @@ export interface HostContext {
    * process.
    */
   files: HostFilesApi;
+  /**
+   * Author-facing OpenTelemetry metrics and session tags. Always present.
+   * Counters and histograms no-op when no meter is running. `setAttributes`
+   * still tags the open session when a collector is attached.
+   */
+  otel: HostOtelApi;
 }
 
 /** Host-facing JSON key-value API attached to {@link HostContext.kv}. */
@@ -704,6 +746,39 @@ export interface HostFilesApi {
   ): string | undefined;
 }
 
+/** Attribute bag accepted by {@link HostOtelApi}. `undefined` values are dropped. */
+export type HostOtelAttributes = Record<
+  string,
+  string | number | boolean | undefined
+>;
+
+/**
+ * Author-facing OpenTelemetry surface on {@link HostContext.otel}.
+ *
+ * Metrics and tags only — no custom spans, and no raw OTel `Meter` /
+ * `Tracer`. First-party names (`cursor.token.usage`, …) and join keys
+ * (`cursor.conversation.id`, `agent_sdk.agent`, …) are reserved.
+ */
+export interface HostOtelApi {
+  /** True when a meter is running and `increment` / `record` export. */
+  readonly enabled: boolean;
+
+  /**
+   * Merge tags onto this host binding. On a session-bound host they join
+   * the open session span and later first-party metrics. Unbound tags
+   * stay on this host instance only.
+   */
+  setAttributes(attributes: HostOtelAttributes): void;
+
+  /** Add 1 to a counter. */
+  increment(name: string, attributes?: HostOtelAttributes): void;
+  /** Add `value` to a counter. */
+  increment(name: string, value: number, attributes?: HostOtelAttributes): void;
+
+  /** Record one histogram observation. */
+  record(name: string, value: number, attributes?: HostOtelAttributes): void;
+}
+
 /** Runtime context handed to a tool's `execute`. */
 export interface ToolContext {
   /** Correlates with `actions.requested` / `action.result` stream events. */
@@ -1422,6 +1497,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;
   /**
@@ -1828,7 +1911,12 @@ export interface ChannelMeta {
 }
 
 export interface ChannelConfig<TState = JsonValue> {
-  /** Route auth chain. Defaults to `[localDevStrict()]`. */
+  /**
+   * Route auth chain. Defaults to `[localDevStrict()]`. Include
+   * `publicEndpoint()` to serve this channel WITHOUT the platform alias
+   * token on Cursor hosting (for webhook senders that cannot attach custom
+   * headers — the handler must verify deliveries itself).
+   */
   auth?: AuthPolicy[];
   routes?: ChannelRoute[];
   /**
@@ -2337,6 +2425,13 @@ export interface ResolvedAgent {
    * (`cwd` is absolute — relative paths resolved against the project root).
    */
   local?: AgentLocalOptions;
+  /**
+   * Built-in harness tool allowlist from {@link AgentConfig.tools}, with
+   * the "mcp" transport grant injected. Named apart from {@link tools}
+   * (the authored `agent/tools/` list). Applied to local turns; cloud
+   * turns fail closed (cloud-runtime agents already fail discovery).
+   */
+  allowedTools?: ToolName[];
   /** Managed-hosting declarations from {@link AgentConfig.hosting}. */
   hosting?: AgentHostingOptions;
   /** Validated turn admission limits from {@link AgentConfig.concurrency}. */
@@ -2374,6 +2469,8 @@ export interface AgentProject {
   storage?: StorageDefinition;
   /** Optional `agent/artifacts.ts` (`defineArtifacts`). */
   artifacts?: ArtifactsDefinition;
+  /** Optional `agent/otel.ts` (`defineOtel`). */
+  otel?: OtelDefinition;
   diagnostics: Diagnostic[];
 }
 
@@ -2456,6 +2553,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[];
@@ -2490,6 +2588,8 @@ export interface RunnerTurnRequest {
   workspaceDir: string;
   /** Run the local harness sandboxed ({@link AgentLocalOptions.sandbox}). */
   sandbox?: boolean;
+  /** Built-in tool allowlist ({@link AgentConfig.tools}, resolved). */
+  tools?: ToolName[];
   /** Absolute path for runner-owned durable state (conversation store). */
   runnerStateDir: string;
   prompt: string;
@@ -2646,6 +2746,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). */