@cursor/july 0.1.7 → 0.1.9

package/src/storage-backends/postgres-kv.ts

@@ -0,0 +1,253 @@
+/**
+ * Postgres `defineStorage` helper on the agent-serve tables
+ * (backend/packages/prisma-bugbot):
+ *
+ *   agent_serve_kv(deployment_id, key, value JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, key)
+ *   agent_serve_eval_runs(deployment_id, agent, run_id, run JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, agent, run_id)
+ *   agent_serve_ab(deployment_id, agent, kind, ref, value JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, agent, kind, ref)
+ *
+ * For Cursor-managed hosting prefer `cursorHostedStorage` from
+ * `@cursor/july/storage/cursor-hosted` — same tables via a control-plane
+ * HTTP proxy (no pod-visible DSN). Use this helper when you supply
+ * `BUGBOTDB_URL` / `AGENT_SERVE_DEPLOYMENT_ID` yourself (self-host).
+ *
+ * `postgresStorage` implements the whole `defineStorage` surface as plain
+ * SQL: the four KV methods against the last-write-wins `agent_serve_kv`
+ * table (sessions, event chunks, continuations, reminders), the `evals`
+ * table against `agent_serve_eval_runs` (one row per playground eval
+ * batch), and the `abs` table against `agent_serve_ab` (`kind = 'sample'`
+ * rows per metric sample plus one `kind = 'snapshot'` row holding the
+ * latest aggregate).
+ *
+ * - KV `put` upserts on the primary key (LWW matches the framework contract).
+ * - KV `list` is a prefix range scan on the PK btree (`key >= p AND key < p||…`
+ *   spelled as LIKE with escaped wildcards, ordered by key).
+ * - `get` returning no row is a definitive miss (`undefined`); a connection
+ *   error throws, so lazy restore fails the follow-up instead of forking
+ *   the session.
+ *
+ * Connection comes from `BUGBOTDB_URL` — the repo-wide convention for the
+ * bugbot Postgres database, whose Prisma package owns these tables' schema
+ * and migrations; locally it falls back to the dev bugbot DB. Non-local
+ * URLs enable TLS (`ssl.rejectUnauthorized`) because PlanetScale requires
+ * SSL even when the vault URL omits `sslmode`.
+ * `deploymentId` scopes rows per deployment (`AGENT_SERVE_DEPLOYMENT_ID`);
+ * the local default keeps dev runs of different checkouts from colliding
+ * only by agent name.
+ *
+ * Callers must pass `Pool` from their own `import { Pool } from "pg"`.
+ * This module must not import `pg` itself: Node resolves modules from
+ * *this* file's directory tree, so a `pg` dep declared only on the
+ * consuming agent package would never be found after a hosted install.
+ */
+
+import type { ABSnapshot } from "../ab.js";
+import type { EvalRunSnapshot } from "../evals.js";
+import type {
+  StorageABTable,
+  StorageConfig,
+  StorageEntry,
+  StorageEvalsTable,
+} from "../storage.js";
+import type { JsonValue } from "../types.js";
+
+/** Minimal `pg.Pool` surface used here (avoids importing `pg` from this path). */
+export interface PostgresQueryable {
+  query<T extends Record<string, unknown> = Record<string, unknown>>(
+    text: string,
+    values?: readonly unknown[]
+  ): Promise<{ rows: T[] }>;
+}
+
+/** `pg.Pool` constructor supplied by the consuming example package. */
+export type PostgresPoolConstructor = new (config?: {
+  connectionString?: string;
+  max?: number;
+  ssl?: boolean | { rejectUnauthorized?: boolean };
+}) => PostgresQueryable;
+
+export interface PostgresStorageOptions {
+  /**
+   * Pass `Pool` from `import { Pool } from "pg"` in the example that declares
+   * the `pg` dependency (hosted installs put it in that package's
+   * `node_modules` only).
+   */
+  Pool: PostgresPoolConstructor;
+  /** Postgres connection string (default: env, then local bugbot dev DB). */
+  databaseUrl?: string;
+  /** Value for the tables' deployment_id column (default: env or "local-dev"). */
+  deploymentId?: string;
+}
+
+type PostgresStorageMethods = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+> & {
+  evals: StorageEvalsTable;
+  abs: StorageABTable;
+};
+
+/** True for local bugbot/dev URLs that do not speak TLS. */
+export function isLocalPostgresUrl(connectionString: string): boolean {
+  try {
+    const host = new URL(connectionString).hostname.toLowerCase();
+    return (
+      host === "localhost" ||
+      host === "127.0.0.1" ||
+      host === "::1" ||
+      host === "[::1]"
+    );
+  } catch {
+    return /@(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(connectionString);
+  }
+}
+
+/** Postgres-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
+export function postgresStorage(
+  options: PostgresStorageOptions
+): PostgresStorageMethods {
+  const connectionString =
+    options.databaseUrl ??
+    process.env.BUGBOTDB_URL ??
+    "postgresql://prisma:prisma@localhost:5432/bugbot";
+  // Prod Bugbot is PlanetScale Postgres: TLS is required and the vault
+  // `BUGBOTDB_URL` often omits `sslmode`. Without an explicit `ssl` option,
+  // `pg` opens plaintext and PlanetScale rejects with "SSL connection is
+  // required" — sessions stay in-memory. Skip TLS only for local hosts.
+  const pool = new options.Pool({
+    connectionString,
+    // Small fixed pool per agent, mirroring the backend's connection_limit
+    // clamp on BUGBOTDB_URL consumers (backend/server/src/prisma.ts).
+    max: 3,
+    ...(isLocalPostgresUrl(connectionString)
+      ? {}
+      : { ssl: { rejectUnauthorized: true } }),
+  });
+  const deploymentId =
+    options.deploymentId ??
+    process.env.AGENT_SERVE_DEPLOYMENT_ID ??
+    "local-dev";
+
+  return {
+    async put(key, value): Promise<void> {
+      await pool.query(
+        `INSERT INTO agent_serve_kv (deployment_id, key, value, updated_at)
+         VALUES ($1, $2, $3::jsonb, now())
+         ON CONFLICT ON CONSTRAINT pk_agent_serve_kv
+         DO UPDATE SET value = EXCLUDED.value, updated_at = now()`,
+        [deploymentId, key, JSON.stringify(value)]
+      );
+    },
+
+    async get(key): Promise<JsonValue | undefined> {
+      const result = await pool.query<{ value: JsonValue }>(
+        `SELECT value FROM agent_serve_kv
+         WHERE deployment_id = $1 AND key = $2`,
+        [deploymentId, key]
+      );
+      return result.rows[0]?.value; // no row ⇒ definitive miss
+    },
+
+    async delete(key): Promise<void> {
+      await pool.query(
+        `DELETE FROM agent_serve_kv WHERE deployment_id = $1 AND key = $2`,
+        [deploymentId, key]
+      );
+    },
+
+    async list(prefix): Promise<StorageEntry[]> {
+      // Escape LIKE wildcards in the prefix so keys containing % or _
+      // (URI-encoded segments cannot, but be safe) match literally.
+      const escaped = prefix.replace(/([\\%_])/g, "\\$1");
+      const result = await pool.query<{ key: string; value: JsonValue }>(
+        `SELECT key, value FROM agent_serve_kv
+         WHERE deployment_id = $1 AND key LIKE $2 ESCAPE '\\'
+         ORDER BY key ASC`,
+        [deploymentId, `${escaped}%`]
+      );
+      return result.rows;
+    },
+
+    // Playground eval batches → agent_serve_eval_runs (one row per run).
+    evals: {
+      async put(run, ctx): Promise<void> {
+        await pool.query(
+          `INSERT INTO agent_serve_eval_runs (deployment_id, agent, run_id, run, updated_at)
+           VALUES ($1, $2, $3, $4::jsonb, now())
+           ON CONFLICT ON CONSTRAINT pk_agent_serve_eval_runs
+           DO UPDATE SET run = EXCLUDED.run, updated_at = now()`,
+          [deploymentId, ctx.agentName, run.runId, JSON.stringify(run)]
+        );
+      },
+      async delete(runId, ctx): Promise<void> {
+        await pool.query(
+          `DELETE FROM agent_serve_eval_runs
+           WHERE deployment_id = $1 AND agent = $2 AND run_id = $3`,
+          [deploymentId, ctx.agentName, runId]
+        );
+      },
+      async list(ctx): Promise<EvalRunSnapshot[]> {
+        const result = await pool.query<{ run: EvalRunSnapshot }>(
+          `SELECT run FROM agent_serve_eval_runs
+           WHERE deployment_id = $1 AND agent = $2`,
+          [deploymentId, ctx.agentName]
+        );
+        return result.rows.map((row) => row.run);
+      },
+    },
+
+    // A/B metrics → agent_serve_ab: sample rows plus one snapshot row.
+    abs: {
+      async putSample(sample, ctx): Promise<void> {
+        await upsertAbRow(pool, {
+          deploymentId,
+          agent: ctx.agentName,
+          kind: "sample",
+          // One boundary event emits a sample per enrolled experiment with
+          // the same sessionId/at — the experiment must be in the row key
+          // or those samples overwrite each other.
+          ref: `${sample.experiment}/${sample.sessionId}/${sample.at}`,
+          value: sample,
+        });
+      },
+      async putSnapshot(snapshot, ctx): Promise<void> {
+        await upsertAbRow(pool, {
+          deploymentId,
+          agent: ctx.agentName,
+          kind: "snapshot",
+          ref: "",
+          value: snapshot,
+        });
+      },
+      async getSnapshot(ctx): Promise<ABSnapshot | undefined> {
+        const result = await pool.query<{ value: JsonValue }>(
+          `SELECT value FROM agent_serve_ab
+           WHERE deployment_id = $1 AND agent = $2 AND kind = 'snapshot' AND ref = ''`,
+          [deploymentId, ctx.agentName]
+        );
+        return result.rows[0]?.value as unknown as ABSnapshot | undefined;
+      },
+    },
+  };
+}
+
+async function upsertAbRow(
+  pool: PostgresQueryable,
+  row: {
+    deploymentId: string;
+    agent: string;
+    kind: "sample" | "snapshot";
+    ref: string;
+    value: unknown;
+  }
+): Promise<void> {
+  await pool.query(
+    `INSERT INTO agent_serve_ab (deployment_id, agent, kind, ref, value, updated_at)
+     VALUES ($1, $2, $3, $4, $5::jsonb, now())
+     ON CONFLICT ON CONSTRAINT pk_agent_serve_ab
+     DO UPDATE SET value = EXCLUDED.value, updated_at = now()`,
+    [row.deploymentId, row.agent, row.kind, row.ref, JSON.stringify(row.value)]
+  );
+}

package/src/storage.ts

@@ -33,7 +33,9 @@
  *
  * Because keys are opaque strings to the sink, new kinds of durable state
  * (channel cursors, thread affinity, …) are new key prefixes — existing
- * sinks store them with no code changes.
+ * sinks store them with no code changes. Authors can also store their own
+ * JSON under `agentkit/v1/{agent}/kv/…` via {@link HostContext.kv}; the
+ * framework still mints the full key from the author-supplied segment.
  *
  * Delivery semantics: writes are **serialized** (one sink call in flight
  * per agent, in order), **bounded** (a sink that falls behind sheds writes
@@ -274,6 +276,7 @@ export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
  * | `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}/reminder/{reminderId}` | `ReminderRecord` |
+ * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via {@link HostContext.kv} |
  *
  * Eval-run and A/B history do not flow through this KV scheme — they have
  * dedicated tables ({@link StorageConfig.evals} / {@link StorageConfig.abs}).
@@ -301,6 +304,13 @@ export const storageKeys = {
     `${STORAGE_KEY_ROOT}/${agent}/reminder/${reminderId}`,
   reminderPrefix: (agent: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/reminder/`,
+  /**
+   * 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/`,
 } as const;
 
 /**

package/src/types.ts

@@ -316,6 +316,28 @@ export interface HostMcpCallResult {
   structuredContent?: JsonObject;
 }
 
+/**
+ * Durable Slack follow-up nudge + ask-claim API attached to {@link HostContext}.
+ * Used for mid-turn inject, boundary resume skip, and delayed-parent dedupe.
+ */
+export interface SlackNudgeHostApi {
+  append(input: {
+    continuationKey: string;
+    sourceTs: string;
+    text: string;
+    author?: string;
+  }): Promise<boolean>;
+  /** Drain pending nudges and return a `<slack_followup>` block, if any. */
+  drainFormatted(continuationKey: string): Promise<string | undefined>;
+  clear(continuationKey: string): Promise<void>;
+  hasUndelivered(continuationKey: string): Promise<boolean>;
+  isDelivered(continuationKey: string, sourceTs: string): Promise<boolean>;
+  /** Claim `channelId:message.ts` exactly once (false = already seen). */
+  tryClaimAsk(channelId: string, messageTs: string): Promise<boolean>;
+  /** Release a claim after a failed send so Slack redelivery can retry. */
+  releaseAsk(channelId: string, messageTs: string): Promise<void>;
+}
+
 /**
  * Shared host services available on every tool / channel / schedule surface.
  * Channel packs attach this as `ctx.host` so handlers can tap GitHub, Slack,
@@ -339,6 +361,29 @@ export interface HostContext {
    * the serve host has attached a {@link ReminderRunner}.
    */
   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.
+   */
+  slackNudges?: SlackNudgeHostApi;
+  /**
+   * Author-facing durable JSON KV (`agentkit/v1/{agent}/kv/…`). Backed by
+   * `agent/storage.ts` (`defineStorage`) when authored; otherwise files
+   * under `--state-root/kv`. Prefer this over ad-hoc files under the
+   * project tree so state survives host replacement.
+   */
+  kv: HostKvApi;
+}
+
+/** Host-facing JSON key-value API attached to {@link HostContext.kv}. */
+export interface HostKvApi {
+  /** Read one value. Miss → `undefined`. */
+  get(key: string): Promise<JsonValue | undefined>;
+  /** Write or replace one value. */
+  put(key: string, value: JsonValue): Promise<void>;
+  /** Remove one key. No-op when missing. */
+  delete(key: string): Promise<void>;
 }
 
 /** Runtime context handed to a tool's `execute`. */
@@ -851,6 +896,11 @@ export interface ChannelSession {
   readonly continuationToken: string | null;
   /** True when this `send()` created the session. */
   readonly isNew: boolean;
+  /**
+   * True when `admission: "coalesce"` enqueued this message behind an
+   * in-flight turn instead of starting immediately (Slack busy path).
+   */
+  readonly coalesced?: boolean;
   readonly info: SessionInfo;
   /** Replay recorded events from `startIndex`, then follow live (NDJSON). */
   getEventStream(options?: {
@@ -919,6 +969,17 @@ export interface SendMessageOptions {
    * store is gone.
    */
   sdkAgentId?: string;
+  /**
+   * Turn admission when a session is already busy.
+   * - `"preempt"` (default) — interrupt the in-flight turn (HTTP / MCP).
+   * - `"coalesce"` — enqueue and return without interrupting (Slack).
+   */
+  admission?: "preempt" | "coalesce";
+  /**
+   * Optional source message timestamp for coalesce queue items. When a
+   * mid-turn nudge already delivered this `sourceTs`, boundary resume skips it.
+   */
+  coalesceSourceTs?: string;
 }
 
 export type SendMessageFn = (
@@ -1183,6 +1244,28 @@ export interface ChannelStartArgs {
   /** Shared host services (MCP / GitHub / Slack). Same as {@link ChannelHandlerArgs.host}. */
   host: HostContext;
   waitUntil(promise: Promise<unknown>): void;
+  /**
+   * Whether a live session already exists for a continuation token on this
+   * channel (includes lazy restore from storage).
+   */
+  hasContinuationSession(continuationToken: string): Promise<boolean>;
+  /**
+   * Whether a model turn is in flight (or being admitted) for the session
+   * addressed by this continuation token.
+   */
+  isContinuationBusy(continuationToken: string): Promise<boolean>;
+  /**
+   * Slack warm-delta watermark: last agent reply ts recorded on the session's
+   * channel state (`lastBotMessageTs`), when present.
+   */
+  getContinuationLastBotMessageTs(
+    continuationToken: string
+  ): Promise<string | undefined>;
+  /**
+   * Interrupt the in-flight turn for a continuation token and clear any
+   * coalesced follow-ups queued behind it. Returns whether work was active.
+   */
+  interruptContinuation(continuationToken: string): Promise<boolean>;
   /**
    * Approve or deny a parked {@link ToolConfig.needsApproval} tool call
    * for a session on this channel. Channel packs (e.g. Slack Block Kit