@cursor/july 0.1.43 → 0.1.46

package/dist/internal/discovery.js

@@ -275,6 +275,13 @@ function loadAgent(ctx, agentDir, options) {
                     message: "builtinTools is not supported on subagents; ignoring.",
                 });
             }
+            if ((config === null || config === void 0 ? void 0 : 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 = yield findModuleFile(agentDir, "artifacts");
             if (artifactsPath !== undefined) {
                 ctx.diagnostics.push({
@@ -299,6 +306,41 @@ function loadAgent(ctx, agentDir, options) {
         const localCwd = resolveAgentCwd(ctx, (_a = config === null || config === void 0 ? void 0 : config.local) === null || _a === void 0 ? void 0 : _a.cwd);
         const localWorkspaceDir = resolveAgentCwd(ctx, (_b = config === null || config === void 0 ? void 0 : config.local) === null || _b === void 0 ? void 0 : _b.workspaceDir);
         const localSandbox = ((_c = config === null || config === void 0 ? void 0 : config.local) === null || _c === void 0 ? void 0 : _c.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 === null || config === void 0 ? void 0 : config.tools;
+        const allowedTools = authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
+            ? authoredAllowlist
+            : [...authoredAllowlist, "mcp"];
+        // 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",
@@ -325,24 +367,19 @@ function loadAgent(ctx, agentDir, options) {
             });
         }
         appendBuiltinTools(ctx, agentDir, tools, config === null || config === void 0 ? void 0 : config.builtinTools);
-        return {
-            name,
-            description: config === null || config === void 0 ? void 0 : config.description,
+        return Object.assign(Object.assign({ name, description: config === null || config === void 0 ? void 0 : config.description, 
             // Root agents always get a concrete model: authored value or DEFAULT_MODEL.
-            model: isValidModelSetting(config === null || config === void 0 ? void 0 : config.model) ? config.model : DEFAULT_MODEL,
-            instructions,
+            model: isValidModelSetting(config === null || config === void 0 ? void 0 : config.model) ? config.model : DEFAULT_MODEL, instructions,
             runtime,
             cloud,
-            local,
-            hosting,
+            local }, (allowedTools === undefined ? {} : { allowedTools })), { hosting,
             concurrency,
             serving,
             tools,
             skills,
             connections,
             subagents,
-            seedFiles,
-        };
+            seedFiles });
     });
 }
 /**

package/dist/internal/durable-session-store.d.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
@@ -21,28 +23,38 @@ export interface StorageCasKvArgs {
     projectRoot: string;
 }
 /**
- * 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 declare function storageCasKv(config: StorageConfig, args: StorageCasKvArgs): SessionLedgerKv;
+export declare function ledgerKeyPrefix(agentName: string): string;
 /**
- * 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.
+ * 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 declare function ledgerKeyPrefix(agentName: string): string;
+export declare function storageCasKv(config: StorageConfig, args: StorageCasKvArgs): SessionLedgerKv;
 /**
- * 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 declare function namespacedKv(store: SessionLedgerKv, namespace: string): SessionLedgerKv;
 //# sourceMappingURL=durable-session-store.d.ts.map

package/dist/internal/durable-session-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durable-session-store.d.ts","sourceRoot":"","sources":["../../src/internal/durable-session-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GACrB,eAAe,CAuBjB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,eAAe,CAOjB"}
+{"version":3,"file":"durable-session-store.d.ts","sourceRoot":"","sources":["../../src/internal/durable-session-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GACrB,eAAe,CA0CjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,eAAe,CAcjB"}

package/dist/internal/durable-session-store.js

@@ -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
@@ -25,10 +27,28 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { keySegment, STORAGE_KEY_ROOT, } from "../storage.js";
 /**
- * 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) {
+    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, args) {
     const ctx = {
@@ -40,7 +60,28 @@ export function storageCasKv(config, args) {
     if (cas === undefined) {
         throw new Error("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 {
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                return (_a = (yield get(key, ctx))) !== null && _a !== void 0 ? _a : undefined;
+            });
+        },
+        put(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield config.put(key, value, ctx);
+            });
+        },
+        delete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield remove(key, ctx);
+            });
+        },
         getWithVersion(key) {
             return __awaiter(this, void 0, void 0, function* () {
                 return yield cas.getWithVersion(key, ctx);
@@ -56,31 +97,35 @@ export function storageCasKv(config, args) {
                 return yield cas.putIfVersion(key, value, expectedVersion, ctx);
             });
         },
+        listKeys(prefix) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield 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) {
-    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, namespace) {
     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: (prefix) => __awaiter(this, void 0, void 0, function* () {
+            const keys = yield store.listKeys(namespace + prefix);
+            return keys.map((key) => key.slice(namespace.length));
+        }),
     };
 }

package/dist/internal/host-otel.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 { Meter } from "@opentelemetry/api";
+import type { HostOtelApi } from "../types.js";
+import type { OtelCollector } from "./otel/collector.js";
+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;
+}
+/** Build the host OpenTelemetry API for one agent process. */
+export declare function createHostOtelApi(options: CreateHostOtelApiOptions): HostOtelSessionApi;
+//# sourceMappingURL=host-otel.d.ts.map

package/dist/internal/host-otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-otel.d.ts","sourceRoot":"","sources":["../../src/internal/host-otel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAsB,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAGnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAqBzD,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,CAAC;CACnD;AAsBD,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,kBAAkB,CAYpB"}

package/dist/internal/host-otel.js

@@ -0,0 +1,162 @@
+/**
+ * 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 { attrs } from "./otel/attrs.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",
+]);
+/** Build the host OpenTelemetry API for one agent process. */
+export function createHostOtelApi(options) {
+    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) {
+    const api = {
+        get enabled() {
+            return state.shared.meter !== undefined;
+        },
+        setAttributes(attributes) {
+            var _a;
+            const cleaned = validateAttributes(attributes);
+            if (state.sessionId === undefined) {
+                Object.assign(state.localTags, cleaned);
+                return;
+            }
+            mergeSessionTags(state, state.sessionId, cleaned);
+            (_a = state.shared.collector) === null || _a === void 0 ? void 0 : _a.setSessionAttributes(state.sessionId, cleaned);
+        },
+        increment(name, valueOrAttributes, maybeAttributes) {
+            var _a;
+            const value = typeof valueOrAttributes === "number" ? valueOrAttributes : 1;
+            const attributes = typeof valueOrAttributes === "number"
+                ? maybeAttributes
+                : valueOrAttributes;
+            (_a = counter(state.shared, name)) === null || _a === void 0 ? void 0 : _a.add(value, emitAttributes(state, attributes));
+        },
+        record(name, value, attributes) {
+            var _a;
+            (_a = histogram(state.shared, name)) === null || _a === void 0 ? void 0 : _a.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, sessionId, incoming) {
+    var _a;
+    const bag = (_a = state.shared.sessionTags.get(sessionId)) !== null && _a !== void 0 ? _a : {};
+    Object.assign(bag, incoming);
+    state.shared.sessionTags.set(sessionId, bag);
+}
+function emitAttributes(state, callSite) {
+    return attrs(Object.assign(Object.assign(Object.assign(Object.assign({}, sessionBag(state)), validateAttributes(callSite)), { "agent_sdk.agent": state.shared.agentName }), (state.sessionId === undefined
+        ? {}
+        : { "cursor.conversation.id": state.sessionId })));
+}
+function sessionBag(state) {
+    var _a;
+    var _b;
+    if (state.sessionId === undefined) {
+        return state.localTags;
+    }
+    const fromCollector = (_a = state.shared.collector) === null || _a === void 0 ? void 0 : _a.getSessionAttributes(state.sessionId);
+    const fromShared = (_b = state.shared.sessionTags.get(state.sessionId)) !== null && _b !== void 0 ? _b : {};
+    return Object.assign(Object.assign(Object.assign({}, fromShared), (fromCollector !== null && fromCollector !== void 0 ? fromCollector : {})), state.localTags);
+}
+function counter(shared, name) {
+    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;
+    }
+    const instrument = shared.meter.createCounter(name);
+    shared.instruments.set(name, { kind: "counter", instrument });
+    return instrument;
+}
+function histogram(shared, name) {
+    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;
+    }
+    const instrument = shared.meter.createHistogram(name);
+    shared.instruments.set(name, { kind: "histogram", instrument });
+    return instrument;
+}
+function validateMetricName(name) {
+    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) {
+    if (attributes === undefined) {
+        return {};
+    }
+    const out = {};
+    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/dist/internal/init-project.js

@@ -517,20 +517,20 @@ function initNextStepEntries(options) {
     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;
@@ -550,9 +550,9 @@ export function printInitGuide() {
     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/