@cursor/july 0.1.62 → 0.1.68

package/src/storage-protocol.ts

@@ -0,0 +1,247 @@
+/**
+ * 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`.
+ *
+ * Additive JSON only — unknown fields are ignored. Do not put ledger
+ * (`durable-session/`) types here; those are coordination-only and must not
+ * appear in the CP session list.
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * Framework-owned key root. All {@link storageKeys} values live under this
+ * prefix so a shared store can route or namespace Agent SDK data.
+ */
+export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
+
+/**
+ * Exact session-record keys: `agentkit/v1/{agent}/session/{sessionId}`.
+ * Rejects `session-events/`, `durable-session/`, and the CP-owned `_cp`
+ * agent name.
+ */
+const DURABLE_SESSION_RECORD_KEY_RE =
+  /^agentkit\/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.
+ *
+ * | 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}/continuation/{channelId}/{token}` | `{ sessionId }` |
+ * | `agentkit/v1/{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}/`,
+  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;
+
+/**
+ * Max bytes a caller-controlled key segment may occupy after URI-encoding.
+ * Chosen so full keys stay well under common backend limits (Postgres btree
+ * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
+ * replaced by their SHA-256 digest, keeping every minted key bounded.
+ */
+export const MAX_KEY_SEGMENT_BYTES = 256;
+
+/**
+ * URI-encode one caller-controlled key segment, substituting a `sha256:…`
+ * digest of the raw value when the encoding exceeds
+ * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
+ * write path and the continuation-lookup path always agree.
+ *
+ * Exported for the session ledger, which builds its `session/` and
+ * `ledger/` keys with the same encoding rules.
+ */
+export function keySegment(raw: string): string {
+  const encoded = encodeURIComponent(raw);
+  if (Buffer.byteLength(encoded, "utf8") <= MAX_KEY_SEGMENT_BYTES) {
+    return encoded;
+  }
+  return `sha256:${createHash("sha256").update(raw, "utf8").digest("hex")}`;
+}
+
+export function isDurableSessionRecordKey(key: string): boolean {
+  const match = DURABLE_SESSION_RECORD_KEY_RE.exec(key);
+  return match !== null && match[1] !== "_cp";
+}
+
+/** List fields of a persisted `SessionRecord`. Unknown properties are dropped. */
+export type DurableSessionRecord = {
+  sessionId: string;
+  channelId: string;
+  mode: string;
+  continuationKey: string | null | undefined;
+  title: string | undefined;
+  turnCount: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/**
+ * Session metadata for history UIs. `running` is omitted unless a live
+ * overlay (the engine process) supplies it — a KV-only reader must not
+ * claim a turn is in flight.
+ */
+export type DurableSessionSummary = {
+  sessionId: string;
+  channelId: string;
+  mode: string;
+  title: string | undefined;
+  turnCount: number;
+  createdAt: string;
+  updatedAt: string;
+  running: boolean | undefined;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Tolerant `SessionRecord` decoder. Extra fields (`auth`, `purpose`, ledger
+ * extras, future keys) are ignored. Returns undefined when required list
+ * fields are missing or the wrong type.
+ */
+export function parseDurableSessionRecord(
+  value: unknown
+): DurableSessionRecord | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const sessionId = stringValue(value.sessionId);
+  const channelId = stringValue(value.channelId);
+  const mode = stringValue(value.mode);
+  const turnCount =
+    typeof value.turnCount === "number" ? value.turnCount : undefined;
+  const createdAt = stringValue(value.createdAt);
+  const updatedAt = stringValue(value.updatedAt);
+  if (
+    sessionId === undefined ||
+    sessionId.length === 0 ||
+    channelId === undefined ||
+    mode === undefined ||
+    turnCount === undefined ||
+    createdAt === undefined ||
+    updatedAt === undefined
+  ) {
+    return undefined;
+  }
+  if (
+    value.continuationKey !== undefined &&
+    value.continuationKey !== null &&
+    typeof value.continuationKey !== "string"
+  ) {
+    return undefined;
+  }
+  const continuationKey = value.continuationKey;
+  return {
+    sessionId,
+    channelId,
+    mode,
+    continuationKey,
+    title: typeof value.title === "string" ? value.title : undefined,
+    turnCount,
+    createdAt,
+    updatedAt,
+  };
+}
+
+export function summarizeDurableSessionRecord(args: {
+  record: DurableSessionRecord;
+  running?: boolean;
+}): DurableSessionSummary {
+  const { record, running } = args;
+  return {
+    sessionId: record.sessionId,
+    channelId: record.channelId,
+    mode: record.mode,
+    title: record.title,
+    turnCount: record.turnCount,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    running,
+  };
+}
+
+/**
+ * Golden persisted record: required list fields plus extras a future engine
+ * might write. Both this package and the CP decoder must accept it.
+ */
+export const GOLDEN_DURABLE_SESSION_RECORD: Record<string, unknown> = {
+  sessionId: "ses_aaaaaaaaaaaaaaaaaaaaaaaa",
+  channelId: "playground",
+  mode: "chat",
+  purpose: "live",
+  continuationKey: "cont_key_1",
+  auth: { kind: "user", userId: 42 },
+  title: "Weather in NYC",
+  turnCount: 3,
+  createdAt: "2026-08-01T12:00:00.000Z",
+  updatedAt: "2026-08-01T12:05:00.000Z",
+  extraUnknownField: { nested: true },
+};

package/src/storage.ts

@@ -52,13 +52,28 @@
  * interface is the durable mirror.
  */
 
-import { createHash } from "node:crypto";
 import type { ABMetricSample } from "./ab.js";
 import type { EvalRunSnapshot } from "./evals.js";
 import type { ABSnapshot } from "./internal/ab-snapshot.js";
 import { brandDefinition } from "./internal/brand.js";
+import { storageKeys } from "./storage-protocol.js";
 import type { JsonValue, KvCasResult, KvVersionedEntry } from "./types.js";
 
+export type {
+  DurableSessionRecord,
+  DurableSessionSummary,
+} from "./storage-protocol.js";
+export {
+  GOLDEN_DURABLE_SESSION_RECORD,
+  isDurableSessionRecordKey,
+  keySegment,
+  MAX_KEY_SEGMENT_BYTES,
+  parseDurableSessionRecord,
+  STORAGE_KEY_ROOT,
+  storageKeys,
+  summarizeDurableSessionRecord,
+} from "./storage-protocol.js";
+
 // ============================================================================
 // Sink interface
 // ============================================================================
@@ -424,115 +439,6 @@ function deriveAbsTable(config: StorageConfig): StorageABTable {
   };
 }
 
-// ============================================================================
-// Key scheme
-// ============================================================================
-
-/**
- * Framework-owned key root. All {@link storageKeys} values live under this
- * prefix so a shared store can route or namespace Agent SDK data.
- */
-export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
-
-/**
- * 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.
- *
- * | 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}/continuation/{channelId}/{token}` | `{ sessionId }` |
- * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via {@link HostContext.kv} |
- * | `agentkit/v1/{agent}/eval-runs/{runId}` | `EvalRunSnapshot` (derived `evals` table) |
- * | `agentkit/v1/{agent}/ab-samples/{experiment}/{sessionId}/{at}` | `ABMetricSample` (derived `abs` table, append-only) |
- * | `agentkit/v1/{agent}/ab-snapshot` | `ABSnapshot` (derived `abs` table, LWW) |
- *
- * 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 {@link StorageConfig.evals} / {@link 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}/`,
-  continuation: (
-    agent: string,
-    channelId: string,
-    continuationKey: string
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
-  /**
-   * Author-facing opaque JSON (see {@link 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;
-
-/**
- * Max bytes a caller-controlled key segment may occupy after URI-encoding.
- * Chosen so full keys stay well under common backend limits (Postgres btree
- * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
- * replaced by their SHA-256 digest, keeping every minted key bounded.
- */
-export const MAX_KEY_SEGMENT_BYTES = 256;
-
-/**
- * URI-encode one caller-controlled key segment, substituting a `sha256:…`
- * digest of the raw value when the encoding exceeds
- * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
- * write path and the continuation-lookup path always agree.
- *
- * Exported for the session ledger, which builds its `session/` and
- * `ledger/` keys with the same encoding rules.
- */
-export function keySegment(raw: string): string {
-  const encoded = encodeURIComponent(raw);
-  if (Buffer.byteLength(encoded, "utf8") <= MAX_KEY_SEGMENT_BYTES) {
-    return encoded;
-  }
-  return `sha256:${createHash("sha256").update(raw, "utf8").digest("hex")}`;
-}
-
 // ============================================================================
 // Policy resolution
 // ============================================================================

package/src/types.ts

@@ -514,9 +514,11 @@ export interface HostContext {
    */
   reminders?: ReminderHostApi;
   /**
-   * Slack ask-dedupe / optional nudge helpers. Always present on a live
-   * {@link SessionEngine} host. Mid-turn nudge inject is not used; busy
-   * Slack follow-ups coalesce and drain at turn boundaries.
+   * Slack ask-dedupe / nudge helpers. Always present on a live
+   * {@link SessionEngine} host. A busy Slack thread's follow-ups queue here
+   * and reach the running agent at its next tool boundary, via the workspace
+   * carrier hook; whatever the carrier does not reach in time still drains
+   * into the boundary turn, deduped by source ts.
    */
   slackNudges?: SlackNudgeHostApi;
   /**
@@ -1078,6 +1080,76 @@ export type ConnectionConfig = (
    * cloud-native account connectors provisioned by the platform.
    */
   hostOnly?: boolean;
+  /**
+   * Per-session auth: called at turn-build time with the session's
+   * {@link SessionInfo}, returning headers merged over the transport's
+   * static `headers` for that session's use of this connection. This is
+   * how a multi-tenant agent injects the caller's identity — it derives
+   * who the session is for host-side and mints a tenant-scoped
+   * credential; the model never sees a tenant parameter and can never
+   * choose the tenant.
+   *
+   * Derive the identity from durable session facts — `session.auth`,
+   * `session.id`, or your channel's own session state. Do **not** key it
+   * off `session.continuationKey`: the HTTP channel rotates the
+   * continuation key after every accepted follow-up, so a tenant mapping
+   * keyed on it silently breaks mid-conversation. (Channels that mint
+   * stable, parseable tokens by design are the exception.)
+   *
+   * Works attached or advertised. Advertised connections
+   * ({@link advertiseTools}) open per-operation clients with the
+   * evaluated headers. Attached connections ride the turn's SDK
+   * `mcpServers`, passed on every send rather than pinned on the cached
+   * per-session agent handle, so every turn — follow-ups, reminder
+   * wakes — runs on headers evaluated for that turn. The cost: when any
+   * attached connection has `auth`, *all* of the agent's attached
+   * connections are configured per send, so the harness opens fresh MCP
+   * clients for them each turn (stdio servers respawn per turn — avoid
+   * pairing an auth'd connection with a stateful stdio server), and
+   * workspace prewarm omits auth'd connections rather than attaching
+   * them without an identity.
+   *
+   * HTTP/SSE transports only, not combinable with `oauth: true`
+   * (discovery rejects both). A callback that throws fails the turn: a
+   * turn never silently runs without the connection's identity. Cloud
+   * turns are refused (cloud-runtime agents fail discovery). `host.mcp`
+   * calls from server tools keep the static headers only.
+   */
+  auth?: ConnectionAuthProvider;
+  /**
+   * Advertise this connection's tools by name instead of leaving them
+   * behind the MCP meta-tools: at turn-build time the engine lists the
+   * connection's tools and synthesizes a named 1:1 passthrough server
+   * tool per entry — the server's own names, descriptions, and live
+   * schemas — merged into the authored `agent/tools/` catalog. The raw
+   * connection is then not attached to the model (it stays available on
+   * `host.mcp`), so each tool appears exactly once.
+   *
+   * Fail-closed: a `listTools` failure, an invalid tool name, or a name
+   * collision (with an authored tool or another advertised connection)
+   * fails the turn — a turn never silently runs with a shrunken toolset.
+   * Local runtime only, like all server tools: a `runtime: "cloud"` agent
+   * fails discovery, and hybrid per-send cloud sessions refuse the turn.
+   * Not combinable with {@link hostOnly} (advertising puts the tools in
+   * the model's toolset; hostOnly means off the model — discovery rejects
+   * the pair). The listing runs once per turn; point this at endpoints
+   * that can answer `tools/list` cheaply.
+   */
+  advertiseTools?: boolean;
+};
+
+/**
+ * Per-session connection auth on {@link ConnectionConfig.auth}: session →
+ * headers merged over the transport's static headers for that session's
+ * turns. See the field docs for the fail-closed semantics.
+ */
+export type ConnectionAuthProvider = (
+  session: SessionInfo
+) => ConnectionAuthResult | Promise<ConnectionAuthResult>;
+
+/** What a {@link ConnectionAuthProvider} returns. */
+export type ConnectionAuthResult = {
+  headers: Record<string, string>;
 };
 
 /** True when the connection authors tools instead of a spawn/URL/peer. */
@@ -1271,7 +1343,27 @@ export type SessionEventPayload =
       type: "turn.completed";
       data: { result?: string; usage?: TurnUsage; cost?: TurnCost };
     }
+  | {
+      /**
+       * The harness accepted the turn and named the run. Emitted once the
+       * send lands, so a channel can show the request id while the turn is
+       * still going rather than after it. Quote it verbatim when correlating
+       * with backend logs — never abbreviated.
+       */
+      type: "turn.bound";
+      data: { requestId: string };
+    }
   | { type: "turn.failed"; data: { message: string } }
+  | {
+      /**
+       * A Slack follow-up queued mid-turn reached the running agent: the
+       * workspace carrier moved it from `pending/` to `delivered/` at a tool
+       * boundary. Channels use this to reposition a live progress message
+       * below the follow-up, which Slack cannot do any other way.
+       */
+      type: "nudge.delivered";
+      data: Record<string, never>;
+    }
   | { type: "session.waiting"; data: Record<string, never> }
   | { type: "session.completed"; data: Record<string, never> }
   | { type: "session.failed"; data: { message: string } };
@@ -2388,6 +2480,10 @@ export interface DiscoveredConnection {
   transport: ConnectionTransport;
   description?: string;
   hostOnly?: boolean;
+  /** Per-session auth from {@link ConnectionConfig.auth} (http/sse only). */
+  auth?: ConnectionAuthProvider;
+  /** Advertise-by-name from {@link ConnectionConfig.advertiseTools}. */
+  advertiseTools?: boolean;
 }
 
 export interface DiscoveredChannel {
@@ -2624,10 +2720,28 @@ export interface RunnerTurnRequest {
   customTools: Record<string, SDKCustomTool>;
   /** MCP servers from `agent/mcp-connections/`. */
   mcpServers: Record<string, ConnectionTransport>;
+  /**
+   * Configure {@link mcpServers} on every send instead of once on the
+   * cached SDK agent handle. Set when an attached connection has
+   * per-session `auth`: its headers are re-evaluated at turn-build time,
+   * and a handle-pinned copy would keep the first turn's credentials until
+   * the handle recycles. The SDK builds the send's MCP session from exactly
+   * this set (fresh clients each turn — stdio servers respawn per turn),
+   * and the create/resume/prewarm options carry no `mcpServers` at all, so
+   * the local executor cache key stays stable while credentials rotate.
+   * Local runtime only; cloud turns with such connections are refused.
+   */
+  perSendMcpServers?: boolean;
   subagents: RunnerSubagent[];
   onUpdate: (update: RunnerUpdate) => void | Promise<void>;
   /** Called once the SDK agent is open so the engine can persist its id. */
   onSdkAgentId?: (sdkAgentId: string) => void | Promise<void>;
+  /**
+   * Called once the harness names the run, before it produces anything.
+   * Surfaces the request id while the turn is still running rather than at
+   * its end.
+   */
+  onRequestId?: (requestId: string) => void | Promise<void>;
   /**
    * Abort the in-flight run when signalled. The engine aborts this when a
    * follow-up message preempts the current turn; the runner maps it to

package/templates/pr-autofixer/agent/lib/drive-schemas.ts

@@ -1,6 +1,9 @@
 import { z } from "zod";
 
-export const driveStartBodySchema = z.object({
+export const driveStartBodySchema: z.ZodObject<{
+  pr: z.ZodString;
+  hint: z.ZodOptional<z.ZodString>;
+}> = z.object({
   pr: z
     .string()
     .describe(