@cursor/july 0.1.108 → 0.1.111

package/dist/storage.d.ts

@@ -4,19 +4,18 @@
  * Author `agent/storage.ts` with {@link defineStorage} to mirror the
  * framework's durable state into storage you own (a database, S3, a data
  * pipeline, …). Without it, state lives under `--state-root` on local disk
- * only, and eval/A/B history stays in process memory.
+ * only, and eval history stays in process memory.
  *
  * The sink is a plain key-value store — put/get/delete/list, no schema —
  * plus a conditional-write group ({@link StorageConfig.cas}; optional).
  * Implementing that small KV core is enough for
- * FULL functionality: eval-run and A/B history are derived over the core
- * when the optional dedicated tables ({@link StorageConfig.evals} and
- * {@link StorageConfig.abs}) are not authored — those groups exist as
- * backend-native optimizations (a real table, an analytics pipeline),
- * not as required-or-lose-history hooks:
+ * FULL functionality: eval-run history is derived over the core when the
+ * optional dedicated table ({@link StorageConfig.evals}) is not authored —
+ * that group exists as a backend-native optimization (a real table, an
+ * analytics pipeline), not as a required-or-lose-history hook:
  *
  * ```ts
- * import { defineStorage } from "@cursor/july/storage";
+ * import { defineStorage } from "@cursor/july/internal/storage";
  *
  * export default defineStorage({
  *   put: (key, value) => db.upsert(key, value),
@@ -25,7 +24,6 @@
  *   list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
  *   cas: { getWithVersion: ..., putIfAbsent: ..., putIfVersion: ..., listKeys: ... },
  *   evals: { put: ..., delete: ..., list: ... }, // eval-runs table
- *   abs: { putSample: ... },                     // A/B table
  * });
  * ```
  *
@@ -50,9 +48,7 @@
  * event log under `--state-root` remains the live source of truth; this
  * interface is the durable mirror.
  */
-import type { ABMetricSample } from "./ab.js";
 import type { EvalRunSnapshot } from "./evals.js";
-import type { ABSnapshot } from "./internal/ab-snapshot.js";
 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, keySegment, MAX_KEY_SEGMENT_BYTES, parseDurableSessionRecord, STORAGE_KEY_ROOT, storageKeys, storageKeysForArchitecture, summarizeDurableSessionRecord, } from "./storage-protocol.js";
@@ -130,21 +126,6 @@ export interface StorageEvalsTable {
     /** All saved runs (any order). Called once when the serve process hydrates. */
     list(ctx: StorageContext): EvalRunSnapshot[] | Promise<EvalRunSnapshot[]>;
 }
-/**
- * Dedicated table for live A/B metrics: one row per cumulative metric
- * sample (unique per `experiment` + `sessionId` + `at` — one boundary
- * event emits a sample per enrolled experiment), plus — optionally — the latest
- * aggregate snapshot so a replacement host with no local sessions can
- * still serve the A/Bs surface.
- */
-export interface StorageABTable {
-    /** Append one cumulative metric sample (turn complete/fail). */
-    putSample(sample: ABMetricSample, ctx: StorageContext): void | Promise<void>;
-    /** Upsert the latest aggregate snapshot (framework-throttled). Optional. */
-    putSnapshot?(snapshot: ABSnapshot, ctx: StorageContext): void | Promise<void>;
-    /** Latest saved aggregate snapshot (replacement-host backfill). Optional. */
-    getSnapshot?(ctx: StorageContext): ABSnapshot | undefined | null | Promise<ABSnapshot | undefined | null>;
-}
 /**
  * Conditional writes (CAS) — the coordination tier of the storage backend
  * contract. Plain storage works without it, so existing backends keep
@@ -152,9 +133,8 @@ export interface StorageABTable {
  * it, so implementing this group yourself only comes up for BYO storage.
  *
  * Grouped under {@link StorageConfig.cas} rather than as loose methods —
- * matching the `evals` / `abs` table groups — so `defineStorage`
- * validates the whole group at once: there is no meaningful
- * half-implementation.
+ * matching the `evals` table group — so `defineStorage` validates the
+ * whole group at once: there is no meaningful half-implementation.
  *
  * Version tokens are opaque per-key strings that change on every
  * successful write (counter, UUID, content hash — whatever is cheap for
@@ -187,14 +167,6 @@ export interface StorageConfig {
      * memory (lost on restart).
      */
     evals?: StorageEvalsTable;
-    /**
-     * Dedicated A/B table — a backend-native optimization, not a
-     * requirement. When omitted, `defineStorage` derives it over the KV
-     * core: `putSample` and `putSnapshot` need only core `put` (always
-     * present), `getSnapshot` additionally needs core `get`. Session event
-     * logs remain the assignment/fold source of truth either way.
-     */
-    abs?: StorageABTable;
     /**
      * Conditional writes (CAS). Optional for plain storage — existing
      * backends keep working without it. The built-in backends (`fileKv`,
@@ -209,11 +181,28 @@ export interface StorageConfig {
      * growing memory; it never stalls the agent loop.
      */
     put(key: string, value: JsonValue, ctx: StorageContext): void | Promise<void>;
+    /**
+     * Store several values in one call. Optional — the coordinator uses it
+     * only when present, so authored sinks keep `put`'s strict one-at-a-time
+     * ordering. Entries belong to one flush and are independent keys; the
+     * implementation may write them in a single backend round trip. Report
+     * per-entry outcomes, index-aligned with the input: one key's failure
+     * must not take down its batch siblings. A thrown rejection is treated
+     * as every entry failing (logged and dropped, at-most-once) — reserve it
+     * for faults that genuinely precede any write.
+     */
+    putMany?(entries: Array<{
+        key: string;
+        value: JsonValue;
+    }>, ctx: StorageContext): Promise<Array<{
+        key: string;
+        error?: unknown;
+    }>>;
     /** Remove a key. Optional — without it, deletions are skipped. */
     delete?(key: string, ctx: StorageContext): void | Promise<void>;
     /**
      * Point lookup. Optional — required for **lazy restore** (resolving a
-     * continuation token on a replacement host) and the A/B backfill.
+     * continuation token on a replacement host).
      * Return `undefined`/`null` only for a **definitive** miss: on the lazy
      * restore path a throw propagates and fails the follow-up (retryable) —
      * a store outage must not read as "unknown token", which would fork the
@@ -241,7 +230,8 @@ export type StorageDefinition = StorageConfig & {
 };
 /**
  * Author the project storage sink (`agent/storage.ts`, default
- * export). See the module doc for semantics and an example.
+ * export). Import from `@cursor/july/internal/storage`, not
+ * `@cursor/july`. See the module doc for semantics and an example.
  */
 export declare function defineStorage(config: StorageConfig): StorageDefinition;
 export declare const STORAGE_DEFAULT_RESTORE_MAX_SESSIONS = 1000;

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/storage.js

@@ -4,19 +4,18 @@
  * Author `agent/storage.ts` with {@link defineStorage} to mirror the
  * framework's durable state into storage you own (a database, S3, a data
  * pipeline, …). Without it, state lives under `--state-root` on local disk
- * only, and eval/A/B history stays in process memory.
+ * only, and eval history stays in process memory.
  *
  * The sink is a plain key-value store — put/get/delete/list, no schema —
  * plus a conditional-write group ({@link StorageConfig.cas}; optional).
  * Implementing that small KV core is enough for
- * FULL functionality: eval-run and A/B history are derived over the core
- * when the optional dedicated tables ({@link StorageConfig.evals} and
- * {@link StorageConfig.abs}) are not authored — those groups exist as
- * backend-native optimizations (a real table, an analytics pipeline),
- * not as required-or-lose-history hooks:
+ * FULL functionality: eval-run history is derived over the core when the
+ * optional dedicated table ({@link StorageConfig.evals}) is not authored —
+ * that group exists as a backend-native optimization (a real table, an
+ * analytics pipeline), not as a required-or-lose-history hook:
  *
  * ```ts
- * import { defineStorage } from "@cursor/july/storage";
+ * import { defineStorage } from "@cursor/july/internal/storage";
  *
  * export default defineStorage({
  *   put: (key, value) => db.upsert(key, value),
@@ -25,7 +24,6 @@
  *   list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
  *   cas: { getWithVersion: ..., putIfAbsent: ..., putIfVersion: ..., listKeys: ... },
  *   evals: { put: ..., delete: ..., list: ... }, // eval-runs table
- *   abs: { putSample: ... },                     // A/B table
  * });
  * ```
  *
@@ -64,13 +62,14 @@ import { storageKeys } from "./storage-protocol.js";
 export { AGENTSDK_STORAGE_KEY_ROOT, agentSdkStorageKeys, frameworkStartLogId, GOLDEN_DURABLE_SESSION_RECORD, isDurableSessionRecordKey, keySegment, MAX_KEY_SEGMENT_BYTES, parseDurableSessionRecord, STORAGE_KEY_ROOT, storageKeys, storageKeysForArchitecture, summarizeDurableSessionRecord, } from "./storage-protocol.js";
 /**
  * Author the project storage sink (`agent/storage.ts`, default
- * export). See the module doc for semantics and an example.
+ * export). Import from `@cursor/july/internal/storage`, not
+ * `@cursor/july`. See the module doc for semantics and an example.
  */
 export function defineStorage(config) {
     if (typeof config.put !== "function") {
         throw new Error("defineStorage: config.put must be a function");
     }
-    for (const hook of ["get", "list", "delete"]) {
+    for (const hook of ["get", "list", "delete", "putMany"]) {
         const value = config[hook];
         if (value !== undefined && typeof value !== "function") {
             throw new Error(`defineStorage: config.${hook} must be a function when set`);
@@ -93,32 +92,20 @@ export function defineStorage(config) {
         const cas = config.cas;
         // A partial group is a bug, not a legacy config: half-implemented CAS
         // would pass the capability probe.
-        const missingCasHooks = casHooks.filter((hook) => typeof cas[hook] !== "function");
+        const missingCasHooks = casHooks.filter(hook => typeof cas[hook] !== "function");
         if (missingCasHooks.length > 0) {
             throw new Error(`defineStorage: ${missingCasHooks
-                .map((hook) => `cas.${hook}`)
+                .map(hook => `cas.${hook}`)
                 .join(", ")} must be ${missingCasHooks.length === 1 ? "a function" : "functions"} when the cas group is set`);
         }
     }
-    if (config.abs !== undefined) {
-        if (typeof config.abs.putSample !== "function") {
-            throw new Error("defineStorage: abs.putSample must be a function when the abs table is set");
-        }
-        for (const hook of ["putSnapshot", "getSnapshot"]) {
-            const value = config.abs[hook];
-            if (value !== undefined && typeof value !== "function") {
-                throw new Error(`defineStorage: abs.${hook} must be a function when set`);
-            }
-        }
-    }
     // Validate eagerly so a bad policy fails at discovery, not first flush.
     resolveStoragePolicy(config.policy);
     // A backend that implements only the KV core gets full functionality:
-    // the dedicated tables are backend-native optimizations, derived over
-    // the core when absent. Authored groups always win.
+    // the dedicated table is a backend-native optimization, derived over
+    // the core when absent. An authored group always wins.
     const derivedEvals = config.evals === undefined ? deriveEvalsTable(config) : undefined;
-    const derivedAbs = config.abs === undefined ? deriveAbsTable(config) : undefined;
-    return brandDefinition("storage", Object.assign(Object.assign(Object.assign({}, config), (derivedEvals === undefined ? {} : { evals: derivedEvals })), (derivedAbs === undefined ? {} : { abs: derivedAbs })));
+    return brandDefinition("storage", Object.assign(Object.assign({}, config), (derivedEvals === undefined ? {} : { evals: derivedEvals })));
 }
 /**
  * Eval-runs table over the KV core: one key per run under
@@ -138,32 +125,10 @@ function deriveEvalsTable(config) {
             var _a;
             var _b;
             const entries = (_b = (yield (_a = config.list) === null || _a === void 0 ? void 0 : _a.call(config, storageKeys.evalRunsPrefix(ctx.agentName), ctx))) !== null && _b !== void 0 ? _b : [];
-            return entries.map((entry) => entry.value);
+            return entries.map(entry => entry.value);
         }),
     };
 }
-/**
- * A/B table over the KV core. Each sample lands as its own key (identity
- * = experiment + sessionId + at, matching the dedicated table's row
- * uniqueness): appending to one array value would need read-modify-write
- * — lost updates under concurrent writers without CAS, and unbounded
- * value growth — while a key per sample keeps `putSample` a blind put
- * with real append-only semantics. The aggregate snapshot lives at one
- * fixed key via plain `put` (last-write-wins is correct for "latest").
- * Requires only core `put`; `getSnapshot` is included when core `get`
- * exists.
- */
-function deriveAbsTable(config) {
-    const get = config.get;
-    return Object.assign({ putSample: (sample, ctx) => config.put(storageKeys.abSample(ctx.agentName, sample.experiment, sample.sessionId, sample.at), sample, ctx), putSnapshot: (snapshot, ctx) => config.put(storageKeys.abSnapshot(ctx.agentName), snapshot, ctx) }, (get === undefined
-        ? {}
-        : {
-            getSnapshot: (ctx) => __awaiter(this, void 0, void 0, function* () {
-                const value = yield get(storageKeys.abSnapshot(ctx.agentName), ctx);
-                return (value !== null && value !== void 0 ? value : undefined);
-            }),
-        }));
-}
 // ============================================================================
 // Policy resolution
 // ============================================================================

package/dist/types.d.ts

@@ -9,7 +9,6 @@
  */
 import type { InteractionUpdate, SDKCustomTool, ToolName } from "@cursor/sdk";
 import type { z } from "zod";
-import type { ABConfigFile } from "./ab.js";
 import type { FileSystem } from "./filesystem.js";
 import type { ContinuationClaim, ContinuationIdentity, MailboxContinuation } from "./internal/continuation-identity.js";
 import type { OtelConfig, OtelDefinition } from "./otel.js";
@@ -25,7 +24,7 @@ export type JsonSchemaObject = Record<string, unknown>;
  * Discriminates the `define*` helper that produced a module's default export
  * so discovery can validate that a file landed in the right authored slot.
  */
-export type DefinitionKind = "agent" | "instructions" | "tool" | "skill" | "extension" | "disabled-tool" | "disabled-connection" | "disabled" | "connection" | "channel" | "http-channel" | "schedule" | "reminder" | "hook" | "eval" | "ab" | "storage" | "artifacts" | "otel" | "result";
+export type DefinitionKind = "agent" | "instructions" | "tool" | "skill" | "extension" | "disabled-tool" | "disabled-connection" | "disabled" | "connection" | "channel" | "http-channel" | "schedule" | "reminder" | "hook" | "eval" | "storage" | "artifacts" | "otel" | "result";
 export interface BrandedDefinition<K extends DefinitionKind> {
     readonly __agentServe: K;
 }
@@ -209,6 +208,19 @@ export interface AgentConfig {
      * you to select a specific architecture.
      */
     architecture?: AgentArchitecture;
+    /**
+     * Persistent hosting for `architecture: "v2"`.
+     *
+     * Default (`false`): each session boots a pod from the release snapshot;
+     * framework and author state are mirrored to Cursor stores because pod
+     * disks are disposable.
+     *
+     * `true`: one long-lived pod per deployment runs each deployed version as
+     * a container over one state directory on the pod's disk. Nothing is
+     * mirrored: that directory is the durable copy. A redeploy starts the new
+     * version beside the old one on the same state, then drains the old one.
+     */
+    persistent?: boolean;
 }
 /** Hosted architecture on {@link AgentConfig.architecture}. */
 export type AgentArchitecture = "v1" | "v2";
@@ -959,8 +971,8 @@ export type DisabledConnectionDefinition = BrandedDefinition<"disabled-connectio
 /**
  * `export default disable()` / `disableSkill()` / `disableHook()` /
  * `disableChannel()` / `disableSchedule()` / `disableSubagent()` /
- * `disableInstructions()` / `disableAB()` / `disableArtifacts()` in a
- * directory mount removes that contribution from the matching overlay slot.
+ * `disableInstructions()` / `disableArtifacts()` in a directory mount
+ * removes that contribution from the matching overlay slot.
  */
 export type DisabledDefinition = BrandedDefinition<"disabled">;
 /** One mounted extension and the names it contributed. */
@@ -988,8 +1000,6 @@ export interface DiscoveredExtension {
     instructions: boolean;
     /** Workspace seed paths the mount contributed. */
     seedFiles: string[];
-    /** Composed A/B experiment names (`<ns>__<name>`). */
-    abs: string[];
     /** Composed artifact kind names (`<ns>__<kind>`). */
     artifactKinds: string[];
 }
@@ -1288,17 +1298,6 @@ export type SessionEventPayload = {
         channelId: string;
         dryRun?: boolean;
     };
-} | {
-    /**
-     * Sticky A/B enrollment for one experiment (`defineAB` under `agent/ab`).
-     * Appended at session creation (before the first turn). `variant` is a
-     * key of the experiment's `variants`, or `null` for sticky skip.
-     */
-    type: "ab.assigned";
-    data: {
-        experiment: string;
-        variant: string | null;
-    };
 } | {
     /** Cursor SDK agent id is known (cloud: `bc-…`; local: session id). */
     type: "agent.bound";
@@ -1525,8 +1524,8 @@ export interface TurnUsage {
 }
 /**
  * Dollar cost of one turn's token usage (one agent loop pass).
- * Recorded on `turn.completed` events so traces, the playground, A/B
- * metrics, and the CLI can aggregate spend. Computed by
+ * Recorded on `turn.completed` events so traces, the playground, and the
+ * CLI can aggregate spend. Computed by
  * `POST /v1/models/estimate-cost` — billed usage events when available
  * (credits, discounts, CTF), otherwise live catalog pricing.
  */
@@ -1547,8 +1546,7 @@ export interface TurnCost {
 export type SessionMode = "chat" | "task";
 /**
  * Why the session exists. `"eval"` is regression traffic (`defineEval` /
- * `agent-sdk eval` / playground Evals) and is excluded from live A/B
- * enrollment. Default `"live"`.
+ * `agent-sdk eval` / playground Evals). Default `"live"`.
  */
 export type SessionPurpose = "live" | "eval";
 /** Read-only view of a session, handed to tools, hooks, and channel events. */
@@ -1564,12 +1562,6 @@ export interface SessionInfo {
     asOf?: string;
     auth: AuthContext | null;
     title?: string;
-    /**
-     * Sticky A/B arms for this session (`defineAB`): experiment name → variant
-     * key, or `null` for sticky skip. Present after enrollment at session
-     * create (live traffic only). Tools/hooks/harness overlays read this.
-     */
-    abs?: Readonly<Record<string, string | null>>;
     /**
      * Channel-local continuation key when the session is addressable for
      * follow-ups / reminders. Null when the session is not re-keyable.
@@ -1589,20 +1581,14 @@ export interface SessionRecord {
     channelId: string;
     mode: SessionMode;
     /**
-     * `"eval"` for harness sessions — skipped by {@link defineAB} enrollment.
-     * Older records omit this (treated as `"live"`).
+     * `"eval"` for harness sessions. Older records omit this (treated as
+     * `"live"`).
      */
     purpose?: SessionPurpose;
     /** Frozen at create from {@link SendMessageOptions.dryRun}. */
     dryRun?: boolean;
     /** Frozen at create from {@link SendMessageOptions.asOf}. */
     asOf?: string;
-    /**
-     * Denormalized sticky A/B arms (mirrors durable `ab.assigned` events) so
-     * the agent loop / tools can read arms without re-folding the log. Source
-     * of truth for stickiness remains the event stream.
-     */
-    abs?: Record<string, string | null>;
     /** Channel-local continuation key; null when the session is not addressable. */
     continuationKey: string | null;
     /**
@@ -1786,8 +1772,8 @@ export interface SendMessageOptions {
     /** Session display title (applied when creating a new session). */
     title?: string;
     /**
-     * Session purpose at create time. `"eval"` skips sticky A/B enrollment
-     * (`defineAB`) so regression runs do not mix into live metrics.
+     * Session purpose at create time. `"eval"` marks regression traffic so
+     * hooks, `defineResult`, and telemetry can tell it from live sessions.
      */
     purpose?: SessionPurpose;
     /**
@@ -1986,6 +1972,11 @@ export interface ChannelHandlerArgs {
      * pass `sessionId` in `tag` input to attribute one).
      */
     artifacts: ArtifactsApi;
+    /** Hosted Slack admission uses this to paint a warm follow-up. */
+    hasContinuationSession?(continuationToken: string): Promise<boolean>;
+    isContinuationBusy?(continuationToken: string): Promise<boolean>;
+    getContinuationLastBotMessageTs?(continuationToken: string): Promise<string | undefined>;
+    interruptContinuation?(continuationToken: string): Promise<boolean>;
 }
 export type ChannelRouteHandler = (request: Request, args: ChannelHandlerArgs) => Response | Promise<Response>;
 /**
@@ -2160,9 +2151,9 @@ export interface ChannelStartArgs {
     artifacts: ArtifactsApi;
 }
 /**
- * Descriptive metadata a channel pack attaches for tooling. Read by
- * discovery / `projectInfo` and CLI helpers (e.g. `agent-sdk github
- * forward`) — it never affects routing or dispatch.
+ * Metadata a channel pack attaches for discovery, `projectInfo`, and CLI
+ * helpers (e.g. `agent-sdk github forward`). Most fields are descriptive;
+ * explicitly documented protocol fields may also be consumed by the host.
  */
 export interface ChannelMeta {
     /** Well-known pack kind, e.g. `"github"` or `"slack"`. */
@@ -2199,6 +2190,24 @@ export interface ChannelMeta {
      * `deploymentEventTypes`.
      */
     factoryEventTypes?: readonly string[];
+    /**
+     * For Slack packs: the Events API event types this channel dispatches on
+     * (`app_mention`, `message`), derived from `engagement`. Extracted into
+     * the deploy manifest as `eventTypes` so hosted v2 fanout subscribes to
+     * exactly these. Local Socket Mode ignores it (the socket delivers
+     * whatever the app manifest subscribed to).
+     */
+    slackEventTypes?: readonly string[];
+    /**
+     * Static agentic-reply protocol for hosted Slack ingress. Only literals
+     * belong here: the control plane persists this declaration at deploy time
+     * and may act before author code starts.
+     */
+    slackReply?: {
+        mode: "agentic";
+        ack: string;
+        placeholder?: string;
+    };
     /**
      * For Slack packs with the opt-in channel watch: the allowlisted channels
      * (ids or `#names`) this channel dispatches on without a mention. Surfaced
@@ -2259,9 +2268,27 @@ export interface HttpChannelConfig {
     onMessage?: (message: string, info: {
         auth: AuthContext | null;
     }) => string | Promise<string>;
+    /**
+     * Bind host state after the control plane names this session's mailbox
+     * key and before `send()`.
+     */
+    onAdmit?: (info: HttpSessionAdmitInfo) => void | Promise<void>;
     /** Stream-event handlers for sessions created over HTTP. */
     events?: ChannelEventHandlers;
 }
+/** Subject of a hosted HTTP startSession, seen by {@link HttpChannelConfig.onAdmit}. */
+export type HttpSessionAdmitInfo = {
+    message: string;
+    sessionKey: string;
+    dryRun?: boolean;
+    asOf?: string;
+    host: HostContext;
+};
+/** Reject a hosted startSession subject from {@link HttpChannelConfig.onAdmit}. */
+export declare class HttpSessionAdmitError extends Error {
+    readonly status: 400;
+    constructor(message: string);
+}
 export type HttpChannelDefinition = HttpChannelConfig & BrandedDefinition<"http-channel">;
 export interface HookContext extends SessionContext {
     agent: {
@@ -2344,15 +2371,23 @@ export interface ResultContext {
     workspaceDir: string;
     /** Full assistant text for the turn. */
     text: string;
+    /**
+     * The commit did not apply; re-run this turn with `message` so the
+     * model can revise. After two repairs the turn fails like a throw.
+     */
+    reject(message: string): never;
 }
 /**
  * Input to `defineResult` (authored at `agent/result.ts`).
- * Parse `ctx.text` in `commit`. Throw to fail the turn.
+ * Parse `ctx.text` in `commit`. Throw to fail the turn. Call
+ * {@link ResultContext.reject} for a model-correctable miss so the
+ * same turn can revise before `turn.completed`.
  */
 export interface ResultConfig {
     /**
      * Host actuation after the model finishes, before `turn.completed`.
-     * Throw to fail the turn. A dry-run session skips this callback.
+     * Throw to fail the turn. `ctx.reject(message)` re-prompts the model
+     * in this turn (two repairs). A dry-run session skips this callback.
      */
     commit: (ctx: ResultContext) => void | Promise<void>;
 }
@@ -2779,14 +2814,6 @@ export interface DiscoveredHook {
     name: string;
     definition: HookDefinition;
 }
-/** Live A/B metrics experiment (`agent/ab.ts` or `agent/ab/<name>.ts`). */
-export interface DiscoveredAB {
-    name: string;
-    /** File stem the experiment was loaded from (`ab` or a path under `ab/`). */
-    source?: string;
-    /** Branded `defineAB({ ... })` config (see `@cursor/july/ab`). */
-    definition: BrandedDefinition<"ab">;
-}
 export interface SeedFile {
     /** Path inside the session workspace. */
     relativePath: string;
@@ -2834,6 +2861,7 @@ export interface ResolvedAgent {
      * continuation defaults onto channels that omitted a selector.
      */
     architecture?: AgentArchitecture;
+    persistent?: boolean;
     tools: DiscoveredTool[];
     skills: DiscoveredSkill[];
     /**
@@ -2858,17 +2886,13 @@ export interface AgentProject {
     agentDir: string;
     name: string;
     agent: ResolvedAgent;
-    /** Built-in HTTP channel config (authored override or default). */
+    /** Built-in HTTP session channel. */
     httpChannel: HttpChannelDefinition;
     channels: DiscoveredChannel[];
     schedules: DiscoveredSchedule[];
     /** Named reminder handlers from `agent/reminders/*` (optional / additive). */
     reminders?: DiscoveredReminder[];
     hooks: DiscoveredHook[];
-    /** Live A/B metric experiments (`defineAB`). */
-    abs: DiscoveredAB[];
-    /** Optional `agent/ab.config.ts` (`defineABConfig`). */
-    abConfig?: ABConfigFile;
     /** Optional `agent/storage.ts` (`defineStorage`). */
     storage?: StorageDefinition;
     /** Optional `agent/artifacts.ts` (`defineArtifacts`). */
@@ -2979,6 +3003,8 @@ export interface AgentProjectInfo {
         deploymentEventTypes?: readonly string[];
         /** Change Monitor checkpoint or Factory issue event types the channel dispatches on, when declared. */
         factoryEventTypes?: readonly string[];
+        /** Slack Events API event types the channel dispatches on, when declared. */
+        slackEventTypes?: readonly string[];
         /** Slack channels watched for posts (opt-in channel watch), when declared. */
         slackChannelPosts?: readonly string[];
     }>;
@@ -2992,14 +3018,6 @@ export interface AgentProjectInfo {
         name: string;
     }>;
     hooks: string[];
-    /** Live A/B experiment names (`defineAB` under `agent/ab`). */
-    abs: string[];
-    /** Playground fold / durable-sink meta from `agent/ab.config.ts`. */
-    abConfig?: {
-        maxPlaygroundSessions?: number;
-        durableSamples: boolean;
-        durableSnapshots: boolean;
-    };
     /** Project storage sink from `agent/storage.ts`, when authored. */
     storage?: {
         name?: string;
@@ -3073,11 +3091,12 @@ export interface RunnerTurnRequest {
     /** Cloud options when {@link runtime} is `"cloud"`. */
     cloud?: AgentCloudOptions;
     /**
-     * Composed instructions ({@link ResolvedAgent.instructions}) for runtimes
-     * whose harness cannot read the workspace `AGENTS.md` — grokbot turns
-     * carry them into the hosted session so they reach the Sand system
-     * prompt. Local turns read the materialized workspace instead and leave
-     * this unset.
+     * Composed instructions ({@link ResolvedAgent.instructions} plus identity
+     * and tool catalog) delivered as the harness system prompt. Local turns
+     * pass them to the Cursor SDK as `systemPrompt`, replacing Cursor's
+     * built-in prompt; grokbot turns carry them into the hosted session so
+     * they reach the Sand system prompt. Cloud turns leave this unset and
+     * inline the same text into the first prompt instead.
      */
     instructions?: string;
     /**