@cursor/july 0.1.101 → 0.1.102

package/src/storage-protocol.ts

@@ -1,119 +1,129 @@
 /**
  * Durable session KV contract: key families plus a tolerant SessionRecord
- * decoder. This is the lockstep surface for the control plane (see
- * `backend/server/src/agentServe/durableSessionProtocol.ts`) so a dashboard
- * list can read Bugbot KV without importing `@cursor/july`.
+ * decoder. Architecture v1 remains in lockstep with the Bugbot-backed control
+ * plane. Architecture v2 uses the same key shape under its AgentSDK root.
  *
  * Additive JSON only — unknown fields are ignored.
  */
 
 import { createHash } from "node:crypto";
 
+/** Legacy architecture-v1 storage root. */
+export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
+
 /**
- * Framework-owned key root. All {@link storageKeys} values live under this
- * prefix so a shared store can route or namespace Agent SDK data.
+ * Architecture-v2 storage root. Hard cutoff: v2 writes and reads this
+ * prefix only. Existing `agentkit/v1` v2 objects are not migrated.
  */
-export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
+export const AGENTSDK_STORAGE_KEY_ROOT = "agentsdk/v1" as const;
 
 /**
- * Exact session-record keys: `agentkit/v1/{agent}/session/{sessionId}`.
+ * Exact session-record keys: `{agentkit|agentsdk}/v1/{agent}/session/{sessionId}`.
  * Rejects `session-events/` and the CP-owned `_cp` agent name.
  */
 const DURABLE_SESSION_RECORD_KEY_RE =
-  /^agentkit\/v1\/([^/]+)\/session\/([^/]+)$/;
+  /^(agentkit|agentsdk)\/v1\/([^/]+)\/session\/([^/]+)$/;
 
 /**
- * The framework-owned key scheme. Keys are a **stable, versioned contract**
- * under {@link STORAGE_KEY_ROOT}: sinks may treat them as opaque strings, or
- * route on prefixes (e.g. event chunks to object storage, everything else
- * to a database). Channel ids and continuation tokens are the only segments
- * that may contain caller-controlled characters; they are URI-encoded, and
- * a segment whose encoding exceeds {@link MAX_KEY_SEGMENT_BYTES} is replaced
- * by a `sha256:…` digest — so every minted key has a bounded length that any
- * backend (VARCHAR columns, btree index tuples, S3 key limits) can store,
- * no matter what a caller stuffs into a token. The substitution is
- * deterministic: writes and continuation lookups build the same key.
+ * Build the framework-owned key scheme under one versioned root. Channel ids
+ * and continuation tokens are URI-encoded, and oversized segments are
+ * replaced by a deterministic `sha256:…` digest.
  *
  * | Key | Value |
  * | --- | --- |
- * | `agentkit/v1/{agent}/session/{sessionId}` | `SessionRecord` |
- * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
- * | `agentkit/v1/{agent}/session-runs/{sessionPublicId}` | One session-level hosted-execution log (executions[] + lastFailure) |
- * | `agentkit/v1/{agent}/logs/{logId}` | Hosted engine stdout/stderr tee (on-disk `start.log`; `ses_…` after send, `wf:{workflowId}` on admission failure) |
- * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
- * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
+ * | `{root}/{agent}/session/{sessionId}` | `SessionRecord` |
+ * | `{root}/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
+ * | `{root}/{agent}/session-runs/{sessionPublicId}` | One session-level hosted-execution log (executions[] + lastFailure) |
+ * | `{root}/{agent}/logs/{logId}` | Hosted engine stdout/stderr tee (on-disk `start.log`; `ses_…` after send, `wf:{workflowId}` on admission failure) |
+ * | `{root}/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
+ * | `{root}/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
  *
  * The `eval-runs` / `ab-samples` / `ab-snapshot` families are minted only
  * by the tables `defineStorage` derives over the KV core; a backend that
  * authors dedicated `StorageConfig.evals` / `StorageConfig.abs` groups never
  * sees them.
  */
-export const storageKeys = {
-  session: (agent: string, sessionId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session/${sessionId}`,
-  sessionPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session/`,
-  sessionEvents: (
-    agent: string,
-    sessionId: string,
-    firstIndex: number
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
-  sessionEventsPrefix: (agent: string, sessionId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/`,
-  /**
-   * One session-level hosted-execution log (v2 only). `sessionPublicId` is
-   * the factory `ses_…` so a throw that never minted a July session still
-   * lands under a stable key. Per-execution rows live inside the document.
-   */
-  sessionRun: (agent: string, sessionPublicId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session-runs/${keySegment(sessionPublicId)}`,
-  sessionRunsPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/session-runs/`,
-  /**
-   * The v2 customer log: the engine stdout/stderr tee (on-disk `start.log`).
-   * `logId` is the factory `ses_…` after a `send`, or
-   * `wf:{workflowId}` / `wf:{workflowId}/{runId}` when admission fails
-   * before a session exists. Skip/task admissions do not write this key.
-   * Stored as raw UTF-8, not JSON — the file store accepts 64 MiB
-   * objects, and this key is flushed in snapshots, not per line.
-   */
-  log: (agent: string, logId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/logs/${keySegment(logId)}`,
-  logsPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/logs/`,
-  continuation: (
-    agent: string,
-    channelId: string,
-    continuationKey: string
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
-  /**
-   * Author-facing opaque JSON (see `HostContext.kv`). `key` is URI-encoded /
-   * digested like other caller-controlled segments.
-   */
-  kv: (agent: string, key: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/kv/${keySegment(key)}`,
-  kvPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/kv/`,
-  /** One playground eval-run snapshot (derived `evals` table). */
-  evalRun: (agent: string, runId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/${keySegment(runId)}`,
-  evalRunsPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/`,
-  /**
-   * One A/B metric sample (derived `abs` table); the segments mirror the
-   * dedicated table's row identity (experiment + sessionId + at).
-   */
-  abSample: (
-    agent: string,
-    experiment: string,
-    sessionId: string,
-    at: string
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/ab-samples/${keySegment(experiment)}/${keySegment(sessionId)}/${keySegment(at)}`,
-  /** Latest aggregate A/B snapshot (derived `abs` table, LWW). */
-  abSnapshot: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/ab-snapshot`,
-} as const;
+function createStorageKeys(root: string) {
+  return {
+    session: (agent: string, sessionId: string): string =>
+      `${root}/${agent}/session/${sessionId}`,
+    sessionPrefix: (agent: string): string => `${root}/${agent}/session/`,
+    sessionEvents: (
+      agent: string,
+      sessionId: string,
+      firstIndex: number
+    ): string =>
+      `${root}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
+    sessionEventsPrefix: (agent: string, sessionId: string): string =>
+      `${root}/${agent}/session-events/${sessionId}/`,
+    /**
+     * One session-level hosted-execution log (v2 only). `sessionPublicId` is
+     * the factory `ses_…` so a throw that never minted a July session still
+     * lands under a stable key. Per-execution rows live inside the document.
+     */
+    sessionRun: (agent: string, sessionPublicId: string): string =>
+      `${root}/${agent}/session-runs/${keySegment(sessionPublicId)}`,
+    sessionRunsPrefix: (agent: string): string =>
+      `${root}/${agent}/session-runs/`,
+    /**
+     * The v2 customer log: the engine stdout/stderr tee (on-disk `start.log`).
+     * `logId` is the factory `ses_…` after a `send`, or
+     * `wf:{workflowId}` / `wf:{workflowId}/{runId}` when admission fails
+     * before a session exists. Skip/task admissions do not write this key.
+     * Stored as raw UTF-8, not JSON — the file store accepts 64 MiB
+     * objects, and this key is flushed in snapshots, not per line.
+     */
+    log: (agent: string, logId: string): string =>
+      `${root}/${agent}/logs/${keySegment(logId)}`,
+    logsPrefix: (agent: string): string => `${root}/${agent}/logs/`,
+    continuation: (
+      agent: string,
+      channelId: string,
+      continuationKey: string
+    ): string =>
+      `${root}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
+    /**
+     * Author-facing opaque JSON (see `HostContext.kv`). `key` is URI-encoded /
+     * digested like other caller-controlled segments.
+     */
+    kv: (agent: string, key: string): string =>
+      `${root}/${agent}/kv/${keySegment(key)}`,
+    kvPrefix: (agent: string): string => `${root}/${agent}/kv/`,
+    /** One playground eval-run snapshot (derived `evals` table). */
+    evalRun: (agent: string, runId: string): string =>
+      `${root}/${agent}/eval-runs/${keySegment(runId)}`,
+    evalRunsPrefix: (agent: string): string => `${root}/${agent}/eval-runs/`,
+    /**
+     * One A/B metric sample (derived `abs` table); the segments mirror the
+     * dedicated table's row identity (experiment + sessionId + at).
+     */
+    abSample: (
+      agent: string,
+      experiment: string,
+      sessionId: string,
+      at: string
+    ): string =>
+      `${root}/${agent}/ab-samples/${keySegment(experiment)}/${keySegment(sessionId)}/${keySegment(at)}`,
+    /** Latest aggregate A/B snapshot (derived `abs` table, LWW). */
+    abSnapshot: (agent: string): string => `${root}/${agent}/ab-snapshot`,
+  } as const;
+}
+
+export type StorageKeys = ReturnType<typeof createStorageKeys>;
+
+/** Architecture-v1 keys. Kept stable for existing deployments. */
+export const storageKeys: StorageKeys = createStorageKeys(STORAGE_KEY_ROOT);
+
+/** Architecture-v2 keys. Hard cutoff onto {@link AGENTSDK_STORAGE_KEY_ROOT}. */
+export const agentSdkStorageKeys: StorageKeys = createStorageKeys(
+  AGENTSDK_STORAGE_KEY_ROOT
+);
+
+export function storageKeysForArchitecture(
+  architecture: "v1" | "v2" | undefined
+): StorageKeys {
+  return architecture === "v2" ? agentSdkStorageKeys : storageKeys;
+}
 
 /**
  * Max bytes a caller-controlled key segment may occupy after URI-encoding.
@@ -164,7 +174,7 @@ export function keySegment(raw: string): string {
 
 export function isDurableSessionRecordKey(key: string): boolean {
   const match = DURABLE_SESSION_RECORD_KEY_RE.exec(key);
-  return match !== null && match[1] !== "_cp";
+  return match !== null && match[2] !== "_cp";
 }
 
 /** List fields of a persisted `SessionRecord`. Unknown properties are dropped. */

package/src/storage.ts

@@ -61,8 +61,11 @@ import type { JsonValue, KvCasResult, KvVersionedEntry } from "./types.js";
 export type {
   DurableSessionRecord,
   DurableSessionSummary,
+  StorageKeys,
 } from "./storage-protocol.js";
 export {
+  AGENTSDK_STORAGE_KEY_ROOT,
+  agentSdkStorageKeys,
   frameworkStartLogId,
   GOLDEN_DURABLE_SESSION_RECORD,
   isDurableSessionRecordKey,
@@ -71,6 +74,7 @@ export {
   parseDurableSessionRecord,
   STORAGE_KEY_ROOT,
   storageKeys,
+  storageKeysForArchitecture,
   summarizeDurableSessionRecord,
 } from "./storage-protocol.js";
 

package/src/tools.ts

@@ -53,7 +53,13 @@
  */
 
 import type { z } from "zod";
+import {
+  forwardTimeArgument,
+  missingTimeWindow,
+  schemaTimeWindowKeys,
+} from "./internal/as-of.js";
 import { brandDefinition } from "./internal/brand.js";
+import { classifyAnnotationsEffect } from "./internal/tool-policy.js";
 import type {
   JsonObject,
   JsonSchemaObject,
@@ -78,6 +84,18 @@ export type {
   ToolNeedsApproval,
   ToolResultContent,
 } from "./types.js";
+/**
+ * Time-window and effect classifiers the host applies to every tool call.
+ * Re-exported for tools that reach other tools themselves (change-monitor
+ * `script`): inner calls skip the host gate, so the sandbox applies the same
+ * forward-time, omitted-window, and read-only filters.
+ */
+export {
+  classifyAnnotationsEffect,
+  forwardTimeArgument,
+  missingTimeWindow,
+  schemaTimeWindowKeys,
+};
 
 /** Input type for `execute`: inferred from a zod schema, JSON otherwise. */
 export type ToolInput<TSchema> = TSchema extends z.ZodTypeAny

package/src/types.ts

@@ -52,6 +52,7 @@ export type DefinitionKind =
   | "skill"
   | "extension"
   | "disabled-tool"
+  | "disabled-connection"
   | "connection"
   | "channel"
   | "http-channel"
@@ -884,6 +885,13 @@ export interface ToolContext {
   emit?: (payload: SessionEventPayload) => void;
   /** The session's frozen `asOf`, or the wall clock. Use instead of `Date.now()`. */
   now(): Date;
+  /**
+   * The session's frozen instant (ISO-8601), when it has one. Present exactly
+   * when this is an `asOf` session. A tool that reaches other tools itself —
+   * the script sandbox — reads it to apply the same forward-time guard to the
+   * calls it makes, which do not pass back through the host's gate.
+   */
+  asOf?: string;
 }
 
 /**
@@ -1134,24 +1142,53 @@ export interface Extension<TConfig = undefined, TInput = TConfig>
   readonly config: TConfig;
 }
 
-/** The mount-independent part of an {@link Extension}. */
+/** The mount-independent part of an {@link Extension}: an agent-shaped tree. */
 export interface ExtensionDeclaration {
   readonly root: string;
   readonly description: string | undefined;
 }
 
+/** A Cursor plugin directory declared by `cursorPlugin`. */
+export interface CursorPluginDeclaration extends ExtensionDeclaration {
+  readonly layout: "cursor-plugin";
+  readonly variables: Record<string, string>;
+}
+
 /** What `agent/extensions/<ns>.ts` default-exports. */
 export interface ExtensionMount extends BrandedDefinition<"extension"> {
-  readonly extension: ExtensionDeclaration;
+  readonly extension: ExtensionDeclaration | CursorPluginDeclaration;
   readonly config: unknown;
 }
 
+/** `cursorPlugin({ ... })`: mount a Cursor plugin directory as an extension. */
+export interface CursorPluginOptions {
+  /**
+   * The plugin directory: the one holding `.cursor-plugin/plugin.json`
+   * (or `.claude-plugin/plugin.json` / `plugin.json`). A relative path
+   * resolves against the project root.
+   */
+  path: string;
+  /**
+   * Values for the `${NAME}` placeholders in the plugin's MCP config, the
+   * variables a Cursor install prompts for. Names the mount omits fall back
+   * to `process.env`; a placeholder nothing resolves fails discovery.
+   */
+  variables?: Record<string, string>;
+}
+
 /**
  * `export default disableTool()` in a directory mount's `tools/<name>.ts`
  * removes the extension's `<ns>__<name>`.
  */
 export type DisabledToolDefinition = BrandedDefinition<"disabled-tool">;
 
+/**
+ * `export default disableConnection()` in a directory mount's
+ * `mcp-connections/<server>.ts` removes the extension's `<ns>__<server>`.
+ */
+export type DisabledConnectionDefinition =
+  BrandedDefinition<"disabled-connection">;
+
 /** One mounted extension and the names it contributed. */
 export interface DiscoveredExtension {
   /** Mount namespace: the filename stem or directory name under `agent/extensions/`. */
@@ -1161,6 +1198,10 @@ export interface DiscoveredExtension {
   tools: string[];
   /** Composed skill names (`<ns>__<name>`), overrides applied. */
   skills: string[];
+  /** Composed MCP connection names (`<ns>__<server>`); Cursor plugin mounts. */
+  connections: string[];
+  /** Composed subagent names (`<ns>__<agent>`); Cursor plugin mounts. */
+  subagents: string[];
 }
 
 // ============================================================================