@cursor/july 0.1.43 → 0.1.46

package/src/ledger.ts

@@ -1,25 +1,40 @@
 /**
- * Session ledger — coordination only. The protocol library that drives
- * the `session/` and `ledger/` key families over a CAS-capable KV:
- * identity creation, lease claim/heartbeat/release, and the fenced
- * commit sequence. The durable inbox (pending events, mailbox payloads,
- * append/drain, the janitor) lands in a follow-up; see
- * `src/ledger/session-ledger.ts` for the trade-off this stage accepts.
+ * Session ledger — KV coordination with a durable inbox. The protocol
+ * library that drives the `session/`, `ledger/`, and `mailbox/` key
+ * families over a CAS-capable KV: identity creation, event append,
+ * lease claim/heartbeat/release, fenced commit, drain, the janitor
+ * loop, and the orphan sweep.
  */
 
+export type {
+  JanitorClaimedSession,
+  JanitorRunResult,
+  LedgerJanitor,
+  LedgerJanitorOptions,
+} from "./ledger/janitor.js";
+export {
+  createLedgerJanitor,
+  DEFAULT_JANITOR_INTERVAL_MS,
+} from "./ledger/janitor.js";
 export type {
   ClaimResult,
   CommitArgs,
   CommitResult,
+  DrainResult,
   EnsureSessionResult,
   HeartbeatResult,
+  LedgerEvent,
+  LedgerEventInput,
   LedgerLease,
   LedgerSnapshot,
   SessionIdentity,
   SessionLedgerKv,
   SessionLedgerOptions,
+  SweepOrphansArgs,
+  SweepOrphansResult,
 } from "./ledger/session-ledger.js";
 export {
+  DEFAULT_ORPHAN_TTL_MS,
   HEARTBEAT_INTERVAL_MS,
   LEASE_TTL_MS,
   LedgerCasExhaustedError,

package/src/storage-backends/cursor-hosted.ts

@@ -129,8 +129,10 @@ type CursorHostedStorageMethods = Required<
 //   AND version = expected`, conflict returns the current row (or
 //   `current: null` when the row is gone).
 // - `POST /internal/agent-serve/storage/kv/list-keys`
-//   `{ prefix }` → `{ keys }` ({@link KvListKeysResponse}) in ascending
-//   key order (prefix scan on the `(deployment_id, key)` primary key).
+//   `{ prefix }` → `{ keys, truncated }` ({@link KvListKeysResponse}) in
+//   ascending key order (prefix scan on the `(deployment_id, key)`
+//   primary key). `truncated: true` means the scan hit the server's row
+//   cap and the list is incomplete; this client throws on it.
 
 /** Wire shape of the `get-with-version` route. `null` ⇒ JSON `undefined`. */
 export interface KvGetWithVersionResponse {
@@ -151,6 +153,11 @@ export interface KvCasResponse {
 /** Wire shape of the `list-keys` route. */
 export interface KvListKeysResponse {
   keys: string[];
+  /**
+   * Set when the scan hit the server's row cap and `keys` is incomplete.
+   * Additive: older servers omit it (treated as `false`).
+   */
+  truncated?: boolean;
 }
 
 function toCasResult(response: KvCasResponse): KvCasResult {
@@ -305,6 +312,14 @@ export function cursorHostedStorage(
           "/internal/agent-serve/storage/kv/list-keys",
           { prefix }
         );
+        if (result.truncated === true) {
+          // Callers (the ledger janitor above all) treat the result as
+          // the complete key set; a silently capped scan means silently
+          // unrecovered sessions. Fail loudly until pagination lands.
+          throw new Error(
+            `cursorHostedStorage: listKeys("${prefix}") exceeded the server's row cap and was truncated; the result is incomplete`
+          );
+        }
         return result.keys;
       },
     },

package/src/types.ts

@@ -8,7 +8,7 @@
  * 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";
@@ -206,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
@@ -220,14 +254,15 @@ export interface AgentConfig {
  * - `"resident"` (default): the in-process session engine owns delivery —
  *   today's behavior, unchanged.
  * - `"ledger"`: every delivery coordinates through the KV session ledger
- *   before its turn runs: session identity, a one-writer-per-session
- *   lease with generation fencing, and a fenced commit sequence.
- *   Requires a store with conditional writes (the `cas` group on
+ *   before its turn runs: the event parks durably in the session mailbox
+ *   (the source ack point moves after that write), a one-writer-per-session
+ *   lease with generation fencing serializes turns, and drained batches
+ *   commit through a fenced sequence. A delivery that finds the lease
+ *   held walks away; the holder drains the parked event, and the janitor
+ *   recovers sessions whose holder died. Requires a store with
+ *   conditional writes and prefix listing (the `cas` group on
  *   `defineStorage`, or an explicit CAS-capable override); startup fails
- *   fast otherwise. This stage is coordination only — there is no
- *   durable inbox yet, so an event arriving while the lease is held
- *   waits in-process and a crash loses it exactly as resident serving
- *   does. The durable mailbox lands in a follow-up.
+ *   fast otherwise.
  */
 export type AgentServingMode = "resident" | "ledger";
 
@@ -506,6 +541,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}. */
@@ -706,6 +747,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. */
@@ -743,6 +817,12 @@ export interface ToolContext {
    * `sessionId` (and `turnId` when known).
    */
   artifacts: ArtifactsApi;
+  /**
+   * Append a session event onto this call's in-flight turn. Same shape as a
+   * Task subagent stream (`parentCallId`, `subagent.called` /
+   * `subagent.completed`). Omitted for scratch `callTool` with no session.
+   */
+  emit?: (payload: SessionEventPayload) => void;
 }
 
 /**
@@ -1398,7 +1478,11 @@ export interface ChannelSession {
    */
   readonly coalesced?: boolean;
   readonly info: SessionInfo;
-  /** Replay recorded events from `startIndex`, then follow live (NDJSON). */
+  /**
+   * Replay recorded events from `startIndex`, then follow live (NDJSON).
+   * A handle from `send()` defaults `startIndex` to this admission so a
+   * resumed continuation does not replay earlier turns.
+   */
   getEventStream(options?: {
     startIndex?: number;
   }): Promise<ReadableStream<Uint8Array>>;
@@ -1838,7 +1922,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[];
   /**
@@ -2347,6 +2436,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}. */
@@ -2503,6 +2599,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;