@cursor/july 0.1.43 → 0.1.46

package/src/internal/cli-deploy.ts

@@ -10,6 +10,7 @@
  */
 
 import { basename, resolve } from "node:path";
+import { isPublicEndpointPolicy } from "../channels.js";
 import {
   type AgentHostingOptions,
   isCursorAccountTransport,
@@ -633,7 +634,8 @@ async function deployOne(
   // truth for egress domains and expected secret names; flags override or
   // augment it. Directories without an agent project (static placeholder
   // deploys) simply have no manifest. The same load supplies the
-  // cursorAccount connection refs for the post-deploy connector auth.
+  // cursorAccount connection refs for the post-deploy connector auth and
+  // the channels declared public via `publicEndpoint()`.
   const manifest = isAgent ? await readDeployManifest(dir) : undefined;
   const hosting = manifest?.hosting;
   const egressAllowedDomains = [
@@ -642,6 +644,21 @@ async function deployOne(
       ...(options.allowDomains ?? []),
     ]),
   ];
+  const publicRoutePaths = (manifest?.publicChannelIds ?? []).map(
+    (channelId) => `/v1/channels/${channelId}`
+  );
+  if (!ctx.json && manifest?.httpChannelPublicEndpoint === true) {
+    ctx.err(
+      `warning: publicEndpoint() on the built-in HTTP channel has no effect on hosting — only custom channels (/v1/channels/…) can be public; the session API always requires the alias token.\n`
+    );
+  }
+  if (!ctx.json && publicRoutePaths.length > 0) {
+    // Security-relevant surface change: say exactly what will be reachable
+    // without the alias token before the deploy is accepted.
+    ctx.err(
+      `  public: ${publicRoutePaths.join(", ")} (served WITHOUT the alias token — these channels authenticate requests themselves)\n`
+    );
+  }
 
   // Today's only source shape: the control plane builds from a git ref (or
   // serves the static placeholder). See DeploySource for the artifact seam.
@@ -655,6 +672,8 @@ async function deployOne(
       ? {}
       : { cursorEventRepos: options.cursorEventsRepos }),
     ...(egressAllowedDomains.length === 0 ? {} : { egressAllowedDomains }),
+    publicRoutePaths:
+      publicRoutePaths.length === 0 ? undefined : publicRoutePaths,
   };
 
   let accepted: DeployAccepted;
@@ -716,6 +735,7 @@ async function deployOne(
     ctx.err(`Deployment ${slug} ended ${detail.status}${errorDetail}\n`);
     return 1;
   }
+  const deployedPublicRoutes = detail.publicRoutePaths ?? [];
   ctx.out(
     `Deployed ${slug} (team ${ctx.teamId})\n` +
       `  status:      running\n` +
@@ -723,7 +743,12 @@ async function deployOne(
       `  kind:        ${detail.deploymentKind}\n` +
       `  alias:       ${aliasUrl}\n` +
       `  playground:  ${aliasUrl}/playground (sign in with the alias token)\n` +
-      `               open: ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n`
+      `               open: ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n` +
+      // Paste-ready webhook URLs: these subtrees skip the alias token, so
+      // the channel handler must verify deliveries (webhook signatures).
+      deployedPublicRoutes
+        .map((path) => `  public:      ${aliasUrl}${path} (no alias token)\n`)
+        .join("")
   );
 
   await runPostDeployConnectorAuth(ctx, options, {
@@ -828,11 +853,23 @@ interface DeployManifest {
     name: string;
     servers: string[] | undefined;
   }>;
+  /**
+   * Channels whose authored auth chain contains `publicEndpoint()`: their
+   * `/v1/channels/<id>` subtree is served through the stable alias WITHOUT
+   * `X-Agent-Alias-Token` (the channel authenticates deliveries itself).
+   */
+  publicChannelIds: string[];
+  /**
+   * `publicEndpoint()` on the built-in HTTP channel — a no-op on hosting
+   * (only `/v1/channels/…` subtrees can be public); surfaced as a warning.
+   */
+  httpChannelPublicEndpoint: boolean;
 }
 
 /**
  * Read the deploy-relevant bits of the project manifest at `dir` in one
- * load: the `hosting` block plus the agent's cursorAccount connections.
+ * load: the `hosting` block, the agent's cursorAccount connections, and the
+ * channels declared public via `publicEndpoint()`.
  */
 async function readDeployManifest(dir: string): Promise<DeployManifest> {
   const project = await loadAgentProject(dir);
@@ -843,6 +880,14 @@ async function readDeployManifest(dir: string): Promise<DeployManifest> {
         ? [{ name: connection.name, servers: connection.transport.servers }]
         : []
     ),
+    publicChannelIds: project.channels
+      .filter((channel) =>
+        (channel.definition.auth ?? []).some(isPublicEndpointPolicy)
+      )
+      .map((channel) => channel.id),
+    httpChannelPublicEndpoint: (project.httpChannel.auth ?? []).some(
+      isPublicEndpointPolicy
+    ),
   };
 }
 
@@ -985,6 +1030,16 @@ export async function cmdDeploymentStatus(
   ) {
     lines.push(`  egress:      ${detail.egressAllowedDomains.join(", ")}`);
   }
+  if (
+    detail.publicRoutePaths !== undefined &&
+    detail.publicRoutePaths.length > 0
+  ) {
+    // Served through the alias WITHOUT X-Agent-Alias-Token (the channel
+    // authenticates deliveries itself).
+    for (const path of detail.publicRoutePaths) {
+      lines.push(`  public:      ${aliasUrl}${path} (no alias token)`);
+    }
+  }
   if (detail.secretNames !== undefined && detail.secretNames.length > 0) {
     lines.push(`  secrets:     ${detail.secretNames.join(", ")}`);
   }

package/src/internal/deploy-client.ts

@@ -69,6 +69,12 @@ export type DeploySource = {
    * deploys — the backend 400s when set on a static deploy.
    */
   egressAllowedDomains?: string[];
+  /**
+   * `/v1/channels/…` subtrees the stable alias serves WITHOUT
+   * `X-Agent-Alias-Token` (channels authored with `publicEndpoint()`).
+   * Only valid on repo-backed deploys.
+   */
+  publicRoutePaths?: string[];
 };
 
 const SLUG_PATTERN = /^[a-z0-9_-]{1,64}$/;
@@ -158,6 +164,8 @@ export interface Deployment {
   cursorEventRepos?: string[];
   /** Normalized egress allowlist for the engine pod. */
   egressAllowedDomains?: string[];
+  /** Channel subtrees the alias serves without `X-Agent-Alias-Token`. */
+  publicRoutePaths?: string[];
   /** Service-account id (`sa_…`); null on legacy rows. */
   serviceAccountId?: string | number | null;
   /**
@@ -297,6 +305,7 @@ const deploymentSchema = z.object({
   lastReconciledAt: z.string().nullable().optional(),
   cursorEventRepos: z.array(z.string()).optional(),
   egressAllowedDomains: z.array(z.string()).optional(),
+  publicRoutePaths: z.array(z.string()).optional(),
   // String ids (`sa_…`) in prod; older mocks/fixtures used numbers. Null on
   // legacy rows that predate service-account-backed deploys.
   serviceAccountId: z.union([z.string(), z.number()]).nullable().optional(),
@@ -441,6 +450,8 @@ export class AgentServeDeployClient {
       ...(args.source.egressAllowedDomains === undefined
         ? {}
         : { egressAllowedDomains: args.source.egressAllowedDomains }),
+      // JSON.stringify drops undefined keys.
+      publicRoutePaths: args.source.publicRoutePaths,
     };
     const raw = await this.request({
       method: "POST",

package/src/internal/discovery.ts

@@ -376,6 +376,14 @@ async function loadAgent(
         message: "builtinTools is not supported on subagents; ignoring.",
       });
     }
+    if (config?.tools !== undefined) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message:
+          "tools is not supported on subagents (they keep the harness task-tool toolset); ignoring.",
+      });
+    }
     const artifactsPath = await findModuleFile(agentDir, "artifacts");
     if (artifactsPath !== undefined) {
       ctx.diagnostics.push({
@@ -415,6 +423,46 @@ async function loadAgent(
   const localCwd = resolveAgentCwd(ctx, config?.local?.cwd);
   const localWorkspaceDir = resolveAgentCwd(ctx, config?.local?.workspaceDir);
   const localSandbox = config?.local?.sandbox === true;
+  // Built-in tool allowlist (top-level `tools`). `[]` is meaningful (no
+  // native built-in tools), so presence is keyed on the field, not on
+  // emptiness. "mcp" is always granted alongside a configured allowlist:
+  // it is transport, not capability — this kit's own server tools ride the
+  // SDK custom-tool MCP path, so omitting it silently breaks
+  // `agent/tools/`, and what MCP actually exposes stays controlled by the
+  // second layer (authored tools, mcp-connections, the harness cwd's
+  // ambient config).
+  const authoredAllowlist = config?.tools;
+  const allowedTools =
+    authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
+      ? authoredAllowlist
+      : [...authoredAllowlist, "mcp" as const];
+  // The allowlist states runtime-agnostic intent, but the SDK cannot
+  // enforce tool restrictions on cloud agents yet — a cloud-runtime agent
+  // that declares one must fail at serve start, never run unrestricted.
+  // (Hybrid per-send cloud sessions fail closed in the session engine.)
+  if (allowedTools !== undefined && runtime === "cloud") {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, join(agentDir, "agent.ts")),
+      message:
+        'tools cannot be enforced on runtime: "cloud" yet (the Cursor SDK rejects tool restrictions on cloud agents). Remove `tools` or run the agent on the local runtime.',
+    });
+  }
+  // `execution: "agent"` tool scripts run through the shell tool. Shell is
+  // a real capability, so it is never injected — but an allowlist that
+  // strands authored scripts deserves a loud diagnostic, not silence.
+  if (
+    allowedTools !== undefined &&
+    !allowedTools.includes("shell") &&
+    tools.some((tool) => tool.execution === "agent")
+  ) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, join(agentDir, "agent.ts")),
+      message:
+        '`tools` omits "shell" but this agent has execution: "agent" tools, which run as shell scripts; the model will not be able to run them.',
+    });
+  }
   if (localCwd !== undefined && localWorkspaceDir !== undefined) {
     ctx.diagnostics.push({
       severity: "warning",
@@ -455,6 +503,7 @@ async function loadAgent(
     runtime,
     cloud,
     local,
+    ...(allowedTools === undefined ? {} : { allowedTools }),
     hosting,
     concurrency,
     serving,

package/src/internal/durable-session-store.ts

@@ -3,11 +3,13 @@
  *
  * Two APIs, one backend: `defineStorage` is the **storage API** (agent
  * state — session records, event chunks, author KV), and the session
- * ledger is the **durable session API** (session identity, leases,
- * fenced commits). The ledger consumes {@link SessionLedgerKv} — exactly
- * the three CAS methods it uses, nothing more; this module adapts a
- * storage backend's `cas` group into that interface, so a deployment's
- * one authored backend serves both APIs by default.
+ * ledger is the **durable session API** (session identity, mailboxes,
+ * leases, fenced commits). The ledger consumes {@link SessionLedgerKv} —
+ * the full CAS-capable KV surface, since the inbox reads/sweeps mailbox
+ * payload blobs (`get`/`put`/`delete`) and scans by prefix (`listKeys`)
+ * on top of the CAS trio; this module adapts a storage backend's methods
+ * into that interface, so a deployment's one authored backend serves
+ * both APIs by default.
  *
  * Calls go straight at the config's methods — NOT through the
  * StorageCoordinator: the coordinator's queue is bounded, serialized, and
@@ -22,6 +24,7 @@ import {
   type StorageConfig,
   type StorageContext,
 } from "../storage.js";
+import type { JsonValue } from "../types.js";
 
 export interface StorageCasKvArgs {
   agentName: string;
@@ -29,10 +32,29 @@ export interface StorageCasKvArgs {
 }
 
 /**
- * Adapt a storage backend's `cas` group into the ledger's KV interface.
- * Throws when the backend does not implement `cas` — the caller turns
- * that into the fail-fast startup error for `serving: "ledger"`. Every
- * call carries a `reason: "coordination"` {@link StorageContext}.
+ * The one place the ledger's physical namespace is minted: the per-agent
+ * prefix for ledger state, following the {@link storageKeys} convention
+ * (`<root>/<agent>/<family>/…`) so a store shared by several ledger-mode
+ * agents (one fileKv dir, one hosted deployment) never mixes their
+ * sessions, leases, or mailboxes — and so each agent's janitor
+ * prefix-scan only ever sees its own ledgers. The extra
+ * `durable-session` segment keeps the ledger's `session/` family out of
+ * `storageKeys.sessionPrefix` scans (storage restore lists
+ * `<root>/<agent>/session/`). The ledger itself never sees this string:
+ * it speaks bare `session/…` / `ledger/…` / `mailbox/…` keys against a
+ * handle that {@link namespacedKv} has already scoped.
+ */
+export function ledgerKeyPrefix(agentName: string): string {
+  return `${STORAGE_KEY_ROOT}/${keySegment(agentName)}/durable-session/`;
+}
+
+/**
+ * Adapt a storage backend into the ledger's KV interface. Throws when
+ * the backend does not implement the `cas` group, or omits `get` /
+ * `delete` (optional for resident-only sinks, but the ledger reads and
+ * sweeps mailbox payload blobs through the same store) — the caller
+ * turns that into the fail-fast startup error for `serving: "ledger"`.
+ * Every call carries a `reason: "coordination"` {@link StorageContext}.
  */
 export function storageCasKv(
   config: StorageConfig,
@@ -49,7 +71,23 @@ export function storageCasKv(
       "storageCasKv: the storage backend does not implement the cas group (conditional writes)"
     );
   }
+  const get = config.get;
+  const remove = config.delete;
+  if (get === undefined || remove === undefined) {
+    throw new Error(
+      "storageCasKv: the storage backend must implement get and delete (the session ledger reads and sweeps payload blobs through the same store)"
+    );
+  }
   return {
+    async get(key): Promise<JsonValue | undefined> {
+      return (await get(key, ctx)) ?? undefined;
+    },
+    async put(key, value): Promise<void> {
+      await config.put(key, value, ctx);
+    },
+    async delete(key): Promise<void> {
+      await remove(key, ctx);
+    },
     async getWithVersion(key) {
       return await cas.getWithVersion(key, ctx);
     },
@@ -59,37 +97,38 @@ export function storageCasKv(
     async putIfVersion(key, value, expectedVersion) {
       return await cas.putIfVersion(key, value, expectedVersion, ctx);
     },
+    async listKeys(prefix) {
+      return await cas.listKeys(prefix, ctx);
+    },
   };
 }
 
 /**
- * The one place the ledger's physical namespace is minted:
- * `agentkit/v1/<agent>/durable-session/` — the {@link STORAGE_KEY_ROOT}
- * conventions with the agent segment encoded like every other
- * caller-controlled segment. The ledger itself never sees this string;
- * it speaks bare `session/…` / `ledger/…` keys against a handle that
- * {@link namespacedKv} has already scoped.
- */
-export function ledgerKeyPrefix(agentName: string): string {
-  return `${STORAGE_KEY_ROOT}/${keySegment(agentName)}/durable-session/`;
-}
-
-/**
- * Scope a raw store handle under a namespace, prepending it to every
- * key on the way in. Applied exactly once, where the engine constructs
- * the ledger's store handle — the same conceptual boundary where
- * `host.kv` gets its agent scoping. Internal: not part of the public kv
- * interface, and callers (including the explicit `durableSessionStore`
- * override) always supply the raw store — they never write prefixes.
+ * Scope a raw store handle under a namespace: every key going in gets it
+ * prepended, and `listKeys` results come back with it **stripped**, so a
+ * caller that lists and then reads/deletes the returned keys stays fully
+ * prefix-free (the janitor scan and the orphan sweep do exactly that).
+ * Applied exactly once, where the engine constructs the ledger's store
+ * handle — the same conceptual boundary where `host.kv` gets its agent
+ * scoping. Internal: not part of the public kv interface, and callers
+ * (including the explicit `durableSessionStore` override) always supply
+ * the raw store — they never write prefixes.
  */
 export function namespacedKv(
   store: SessionLedgerKv,
   namespace: string
 ): SessionLedgerKv {
   return {
+    get: (key) => store.get(namespace + key),
+    put: (key, value) => store.put(namespace + key, value),
+    delete: (key) => store.delete(namespace + key),
     getWithVersion: (key) => store.getWithVersion(namespace + key),
     putIfAbsent: (key, value) => store.putIfAbsent(namespace + key, value),
     putIfVersion: (key, value, expectedVersion) =>
       store.putIfVersion(namespace + key, value, expectedVersion),
+    listKeys: async (prefix) => {
+      const keys = await store.listKeys(namespace + prefix);
+      return keys.map((key) => key.slice(namespace.length));
+    },
   };
 }

package/src/internal/host-otel.ts

@@ -0,0 +1,252 @@
+/**
+ * Author-facing OpenTelemetry surface for {@link HostContext.otel}.
+ *
+ * Always present on `ctx.host`. Counters and histograms no-op when no meter
+ * is running. `setAttributes` still tags the open session when a collector
+ * is attached. `forSession` is engine-only so a tool cannot retarget another
+ * conversation's tags.
+ */
+
+import type { Counter, Histogram, Meter } from "@opentelemetry/api";
+import type { HostOtelApi, HostOtelAttributes } from "../types.js";
+import type { AttrValue } from "./otel/attrs.js";
+import { attrs } from "./otel/attrs.js";
+import type { OtelCollector } from "./otel/collector.js";
+
+const METRIC_NAME = /^[A-Za-z][A-Za-z0-9_./-]*$/;
+
+const RESERVED_METRICS = new Set([
+  "cursor.token.usage",
+  "cursor.tool.calls",
+  "cursor.cost.usage",
+  "agent_sdk.session.count",
+  "agent_sdk.turn.count",
+  "agent_sdk.subagent.count",
+  "agent_sdk.http.duration",
+]);
+
+const RESERVED_ATTRIBUTES = new Set([
+  "cursor.conversation.id",
+  "agent_sdk.agent",
+  "agent_sdk.turn_id",
+  "agent_sdk.framework",
+]);
+
+export interface CreateHostOtelApiOptions {
+  agentName: string;
+  meter?: Meter;
+  collector?: OtelCollector;
+  /** Session bound for join tags; prefer {@link HostOtelSessionApi.forSession}. */
+  sessionId?: string;
+}
+
+/** Engine-only binding. Not part of the public {@link HostOtelApi}. */
+export interface HostOtelSessionApi extends HostOtelApi {
+  forSession(sessionId: string): HostOtelSessionApi;
+}
+
+interface CachedInstrument {
+  kind: "counter" | "histogram";
+  instrument: Counter | Histogram;
+}
+
+interface SharedState {
+  agentName: string;
+  meter: Meter | undefined;
+  collector: OtelCollector | undefined;
+  instruments: Map<string, CachedInstrument>;
+  /** Used when no collector is attached so bound instances still share tags. */
+  sessionTags: Map<string, Record<string, AttrValue>>;
+}
+
+interface BoundState {
+  shared: SharedState;
+  sessionId: string | undefined;
+  localTags: Record<string, AttrValue>;
+}
+
+/** Build the host OpenTelemetry API for one agent process. */
+export function createHostOtelApi(
+  options: CreateHostOtelApiOptions
+): HostOtelSessionApi {
+  return createBoundHostOtelApi({
+    shared: {
+      agentName: options.agentName,
+      meter: options.meter,
+      collector: options.collector,
+      instruments: new Map(),
+      sessionTags: new Map(),
+    },
+    sessionId: options.sessionId,
+    localTags: {},
+  });
+}
+
+function createBoundHostOtelApi(state: BoundState): HostOtelSessionApi {
+  const api: HostOtelSessionApi = {
+    get enabled(): boolean {
+      return state.shared.meter !== undefined;
+    },
+
+    setAttributes(attributes) {
+      const cleaned = validateAttributes(attributes);
+      if (state.sessionId === undefined) {
+        Object.assign(state.localTags, cleaned);
+        return;
+      }
+      mergeSessionTags(state, state.sessionId, cleaned);
+      state.shared.collector?.setSessionAttributes(state.sessionId, cleaned);
+    },
+
+    increment(
+      name: string,
+      valueOrAttributes?: number | HostOtelAttributes,
+      maybeAttributes?: HostOtelAttributes
+    ) {
+      const value =
+        typeof valueOrAttributes === "number" ? valueOrAttributes : 1;
+      const attributes =
+        typeof valueOrAttributes === "number"
+          ? maybeAttributes
+          : valueOrAttributes;
+      counter(state.shared, name)?.add(
+        value,
+        emitAttributes(state, attributes)
+      );
+    },
+
+    record(name, value, attributes) {
+      histogram(state.shared, name)?.record(
+        value,
+        emitAttributes(state, attributes)
+      );
+    },
+
+    forSession(sessionId) {
+      const trimmed = sessionId.trim();
+      if (trimmed === "") {
+        throw new Error("host.otel.forSession requires a non-empty session id");
+      }
+      return createBoundHostOtelApi({
+        shared: state.shared,
+        sessionId: trimmed,
+        localTags: {},
+      });
+    },
+  };
+  return api;
+}
+
+function mergeSessionTags(
+  state: BoundState,
+  sessionId: string,
+  incoming: Record<string, AttrValue>
+): void {
+  const bag = state.shared.sessionTags.get(sessionId) ?? {};
+  Object.assign(bag, incoming);
+  state.shared.sessionTags.set(sessionId, bag);
+}
+
+function emitAttributes(
+  state: BoundState,
+  callSite: HostOtelAttributes | undefined
+): Record<string, AttrValue> {
+  return attrs({
+    ...sessionBag(state),
+    ...validateAttributes(callSite),
+    "agent_sdk.agent": state.shared.agentName,
+    ...(state.sessionId === undefined
+      ? {}
+      : { "cursor.conversation.id": state.sessionId }),
+  });
+}
+
+function sessionBag(state: BoundState): Record<string, AttrValue> {
+  if (state.sessionId === undefined) {
+    return state.localTags;
+  }
+  const fromCollector = state.shared.collector?.getSessionAttributes(
+    state.sessionId
+  );
+  const fromShared = state.shared.sessionTags.get(state.sessionId) ?? {};
+  return {
+    ...fromShared,
+    ...(fromCollector ?? {}),
+    ...state.localTags,
+  };
+}
+
+function counter(shared: SharedState, name: string): Counter | undefined {
+  validateMetricName(name);
+  if (shared.meter === undefined) {
+    return undefined;
+  }
+  const existing = shared.instruments.get(name);
+  if (existing !== undefined) {
+    if (existing.kind !== "counter") {
+      throw new Error(`host.otel metric "${name}" is already a histogram`);
+    }
+    return existing.instrument as Counter;
+  }
+  const instrument = shared.meter.createCounter(name);
+  shared.instruments.set(name, { kind: "counter", instrument });
+  return instrument;
+}
+
+function histogram(shared: SharedState, name: string): Histogram | undefined {
+  validateMetricName(name);
+  if (shared.meter === undefined) {
+    return undefined;
+  }
+  const existing = shared.instruments.get(name);
+  if (existing !== undefined) {
+    if (existing.kind !== "histogram") {
+      throw new Error(`host.otel metric "${name}" is already a counter`);
+    }
+    return existing.instrument as Histogram;
+  }
+  const instrument = shared.meter.createHistogram(name);
+  shared.instruments.set(name, { kind: "histogram", instrument });
+  return instrument;
+}
+
+function validateMetricName(name: string): void {
+  if (!METRIC_NAME.test(name)) {
+    throw new Error(
+      `host.otel metric name "${name}" must match [A-Za-z][A-Za-z0-9_./-]*`
+    );
+  }
+  if (RESERVED_METRICS.has(name)) {
+    throw new Error(`host.otel metric name "${name}" is reserved`);
+  }
+}
+
+function validateAttributes(
+  attributes: HostOtelAttributes | undefined
+): Record<string, AttrValue> {
+  if (attributes === undefined) {
+    return {};
+  }
+  const out: Record<string, AttrValue> = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value === undefined) {
+      continue;
+    }
+    if (RESERVED_ATTRIBUTES.has(key)) {
+      throw new Error(
+        `host.otel attribute "${key}" is reserved; the runtime always sets it`
+      );
+    }
+    if (
+      typeof value !== "string" &&
+      typeof value !== "number" &&
+      typeof value !== "boolean"
+    ) {
+      throw new Error(
+        `host.otel attribute "${key}" must be a string, number, or boolean`
+      );
+    }
+    out[key] = value;
+  }
+  return out;
+}

package/src/internal/init-project.ts

@@ -699,20 +699,20 @@ function initNextStepEntries(options: InitNextStepsOptions): Array<{
   if (cd !== undefined) {
     steps.push({ command: cd });
   }
-  if (!options.cliOnPath) {
-    steps.push({
-      command: 'export PATH="$PWD/node_modules/.bin:$PATH"',
-      note: "use the project-local agent-sdk bin",
-    });
-  }
   if (!options.signedIn) {
+    const login = options.cliOnPath
+      ? `${CLI_COMMAND_NAME} login`
+      : `npx ${PACKAGE_NAME} login`;
     steps.push({
-      command: `${CLI_COMMAND_NAME} login`,
+      command: login,
       note: "connect your Cursor account (powers model turns)",
     });
   }
+  const dev = options.cliOnPath
+    ? `${CLI_COMMAND_NAME} dev`
+    : `npx ${PACKAGE_NAME} dev`;
   steps.push({
-    command: `${CLI_COMMAND_NAME} dev`,
+    command: dev,
     note: "start the local playground",
   });
   return steps;
@@ -739,9 +739,9 @@ export function printInitGuide(): void {
   process.stdout.write(`${CLI_COMMAND_NAME} — coding agent setup
 
 Scaffold a project, then open the playground:
-  npx ${PACKAGE_NAME} init ./my-agent   # installs deps + puts agent-sdk on PATH
+  npx ${PACKAGE_NAME} init ./my-agent   # installs deps + links agent-sdk onto PATH
   npx ${PACKAGE_NAME} init ./my-triage --template triage   # start from a template (agent-sdk templates: triage)
-  cd ./my-agent && ${CLI_COMMAND_NAME} dev
+  cd ./my-agent && agent-sdk dev        # or: npx ${PACKAGE_NAME} dev
 
 Recommended loop once the project exists (from the project directory):
   1. Edit agent/ + tools under agent/tools/