@cursor/july 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -124,6 +124,20 @@
       "import": "./dist/storage.js",
       "default": "./dist/storage.js"
     },
+    "./storage/file-kv": {
+      "anysphere-source": "./src/storage-backends/file-kv.ts",
+      "bun": "./src/storage-backends/file-kv.ts",
+      "types": "./dist/storage-backends/file-kv.d.ts",
+      "import": "./dist/storage-backends/file-kv.js",
+      "default": "./dist/storage-backends/file-kv.js"
+    },
+    "./storage/postgres-kv": {
+      "anysphere-source": "./src/storage-backends/postgres-kv.ts",
+      "bun": "./src/storage-backends/postgres-kv.ts",
+      "types": "./dist/storage-backends/postgres-kv.d.ts",
+      "import": "./dist/storage-backends/postgres-kv.js",
+      "default": "./dist/storage-backends/postgres-kv.js"
+    },
     "./package.json": {
       "anysphere-source": "./package.json",
       "bun": "./package.json",

package/skills/framework-map/SKILL.md

@@ -97,10 +97,12 @@ Two handles, two owners:
 - **sessionId** — runtime-owned handle for streaming/inspection
   (`GET /v1/session/:id/stream?startIndex=N`, durable NDJSON replay).
 
-A follow-up to a busy session **interrupts the in-flight turn** and waits
-for it to settle before the new turn sends. `POST /v1/session/:id/stop`
-interrupts without sending. Session-bound deterministic tool calls are
-rejected with `409 session_busy` while a turn runs.
+A follow-up to a busy HTTP/MCP session **interrupts the in-flight turn**
+and waits for it to settle before the new turn sends. Slack uses
+**coalesce** instead (enqueue + boundary drain; see
+`docs/reference/sessions.md`). `POST /v1/session/:id/stop` interrupts
+without sending. Session-bound deterministic tool calls are rejected with
+`409 session_busy` while a turn runs.
 
 Key built-in routes (each agent, under `/<slug>` in multi-agent mode):
 `POST /v1/session`, `POST /v1/session/:id`, `GET /v1/session/:id/stream`,

package/src/bin/agent-serve.ts

@@ -29,6 +29,7 @@ import {
   cmdCall,
   cmdChat,
   cmdEval,
+  cmdEvalStatus,
   cmdInit,
   cmdLogs,
   cmdPlayground,
@@ -88,10 +89,17 @@ Usage:
   ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
                           [--session <id>] [--slug <slug>] [--team <id>]
   ${CLI} init        [dir] [--json]
+  ${CLI} mcp         --prod [--slug <slug>] [--team <id>] [--dir <path>]
+                          | --url <baseUrl> [--bearer-token <t>]
+  ${CLI} mcp install [--name <serverName>] [--print] [--json]
+                          (same target flags as mcp)
   ${CLI} eval        [--dir <path>] [evalId...] [--list] [--json]
                           [--tag <tag>]... [--verbose] [--timeout-ms <n>]
-                          [--no-stream] [--local | --url <baseUrl>] [--slug <slug>]
+                          [--no-stream] [--no-wait]
+                          [--prod | --url <baseUrl>] [--slug <slug>]
                           [--team <id>]
+  ${CLI} eval status [runId] --prod|--url <baseUrl> [--dir <path>] [--json]
+                          [--slug <slug>] [--team <id>]
   ${CLI} info        [--dir <path>] [--json]
   ${CLI} validate    [--dir <path>]
   ${CLI} login       [--api-key <key>] [--key-name <name>]
@@ -154,12 +162,29 @@ Commands:
               run login when unsigned, then print next steps. --json is
               machine-readable and never blocks on login. No directory:
               print the setup guide.
+  mcp         Serve this agent's MCP endpoint over stdio for MCP clients
+              that spawn local servers (e.g. Cursor). Proxies
+              newline-delimited JSON-RPC to <target>/v1/mcp. --prod resolves
+              the hosted deployment with the signed-in Cursor account and
+              re-mints short-lived engine credentials as they expire;
+              --url targets a running server. stdout is reserved for the
+              MCP wire. \`mcp install\` writes the matching entry into
+              ~/.cursor/mcp.json (--print to preview; --name to override
+              the server name).
   eval        Run filesystem evals under evals/**/*.eval.ts (streams on a TTY).
-              Runs against the team's hosted deployment by default (slug from
-              --slug or the directory name); pass --local for an ephemeral
-              local server, or --url for a running one. Pass evalId args to
-              select: one datapoint (weather/nyc), a whole file (weather →
-              all cases in that file), several of either, or omit to run all.
+              Default: ephemeral local harness against evals on disk. Pass
+              --prod to kick off the batch on the team's hosted deployment
+              (slug from --slug or the directory name) via /v1/dev/evals/runs
+              so results appear in the playground and persist when the agent
+              declares an evals storage table; or --url for a running server
+              (same server-side path). With --prod/--url, pass --no-wait to
+              return the runId immediately without polling; check later with
+              \`${CLI} eval status <runId> --prod\` (omit runId to list recent
+              runs; exit 3 while still running). The status subcommand only
+              binds when --prod/--url is set, so an eval id named status still
+              runs locally. Pass evalId args to select: one datapoint
+              (weather/nyc), a whole file (weather → all cases in that file),
+              several of either, or omit to run all.
   info        Print the discovered agent surface (tools, skills, channels, ...).
   validate    Check the project(s) and exit non-zero on error diagnostics.
   login       Sign the host in to Cursor: browser sign-in mints a named,
@@ -194,7 +219,8 @@ Agent loop:
   ${CLI} validate --dir .
   ${CLI} info --dir . --json
   ${CLI} run --dir . --message "..."
-  ${CLI} eval --local --dir .
+  ${CLI} eval --dir .
+  ${CLI} eval --prod --dir .
   ${CLI} dev .
 
 Options:
@@ -233,15 +259,14 @@ Options:
   --prod             chat/resume/run/call/eval/logs/sessions/session/playground:
                      use the team's hosted deployment. Slug from --slug or the
                      --dir basename. Mutually exclusive with --url. Requires
-                     \`${CLI} login\`. (eval already defaults to the
-                     deployment; there --prod is just being explicit.)
-  --local            eval: run against an ephemeral local server instead of
-                     the hosted deployment. Mutually exclusive with --url.
+                     \`${CLI} login\`. For eval, this is how you opt into the
+                     persisted server-side batch (default is local).
   --once             logs: print current progress / log buffer once and exit
                      (default is to follow).
   --print            playground: print the URL only; do not open a browser.
-  --no-wait          deploy/stop: return right after the request is accepted
-                     instead of polling until a terminal status.
+  --no-wait          deploy/stop/eval: return right after the request is
+                     accepted instead of polling until a terminal status.
+                     For eval, prints the runId (deployment / --url only).
   --no-playground    Disable the bundled web playground at /playground (also skips
                      auto-build / HMR).
   --no-docs          Disable the documentation site at /docs (also skips its
@@ -352,7 +377,6 @@ async function main(argv: string[]): Promise<number> {
       "no-docs": { type: "boolean", default: false },
       url: { type: "string" },
       prod: { type: "boolean", default: false },
-      local: { type: "boolean", default: false },
       message: { type: "string", multiple: true },
       input: { type: "string" },
       "messages-file": { type: "string" },
@@ -407,8 +431,9 @@ async function main(argv: string[]): Promise<number> {
   const dir = values.dir ?? ".";
 
   // Best-effort, cached, and silent on failure. `update` does its own fresh
-  // lookup, and --json runs stay quiet for machine consumers.
-  if (command !== "update" && values.json !== true) {
+  // lookup, --json runs stay quiet for machine consumers, and `mcp` skips it
+  // so MCP client spawns stay fast (stdout there is the protocol wire).
+  if (command !== "update" && command !== "mcp" && values.json !== true) {
     await warnIfOutdated();
   }
 
@@ -475,6 +500,22 @@ async function main(argv: string[]): Promise<number> {
       });
     }
 
+    case "mcp": {
+      const { cmdMcp } = await import("../internal/cli-mcp.js");
+      return cmdMcp(positionals[0], {
+        dir,
+        slug: values.slug,
+        team: values.team,
+        apiKey: values["api-key"],
+        url: values.url,
+        prod: values.prod,
+        bearerToken: values["bearer-token"],
+        name: values.name,
+        print: values.print,
+        json: values.json,
+      });
+    }
+
     case "login": {
       const { cmdLogin } = await import("../internal/cli-cursor.js");
       return cmdLogin({
@@ -624,6 +665,26 @@ async function main(argv: string[]): Promise<number> {
     }
 
     case "eval": {
+      // Remote status subcommand only when targeting --prod/--url. Otherwise
+      // the bare token "status" is a normal eval id (evals/status.eval.ts).
+      if (
+        positionals[0] === "status" &&
+        (values.prod === true || values.url !== undefined)
+      ) {
+        return cmdEvalStatus(
+          positionals[1],
+          axFromOptions({
+            dir,
+            json: values.json,
+            url: values.url,
+            prod: values.prod,
+            team: values.team,
+            apiKey: values["api-key"],
+            slug: values.slug,
+            bearerToken: values["bearer-token"],
+          })
+        );
+      }
       return cmdEval(
         axFromOptions({
           dir,
@@ -634,7 +695,7 @@ async function main(argv: string[]): Promise<number> {
           tags: values.tag,
           url: values.url,
           prod: values.prod,
-          local: values.local,
+          noWait: values["no-wait"],
           team: values.team,
           apiKey: values["api-key"],
           slug: values.slug,
@@ -1052,7 +1113,7 @@ function axFromOptions(
     toolInput: partial.toolInput,
     url: partial.url,
     prod: partial.prod,
-    local: partial.local,
+    noWait: partial.noWait,
     team: partial.team,
     apiKey: partial.apiKey,
     fetchImpl: partial.fetchImpl,

package/src/channels/slack/channel-watch.ts

@@ -6,7 +6,10 @@
  * - Top-level posts only by default; thread replies never dispatch unless
  *   `posts: "all"` is configured.
  * - Posts that @mention the bot are skipped here (the `app_mention` path
- *   owns them), and bot-authored posts are dropped upstream in parsing.
+ *   owns them).
+ * - Bot-authored posts are dropped unless `includeBotPosts` is configured
+ *   (alert feeds / webhook integrations); the watching bot's own posts are
+ *   always dropped either way (loop safety).
  * - An optional debounce window lets rapid edits settle: edits update the
  *   pending text, deleting the post cancels the dispatch.
  */
@@ -114,11 +117,14 @@ export function createChannelPostWatcher(args: {
   allowlist: SlackChannelAllowlist;
   /** Bot user id (from `auth.test`) so bot mentions route via app_mention. */
   getBotUserId: () => string | undefined;
+  /** This app's own `bot_id` (from `auth.test`) for self-post loop safety. */
+  getBotId?: () => string | undefined;
   dispatch: (message: SlackMessage, eventId?: string) => void;
   log?: SlackLog;
 }): ChannelPostWatcher {
   const log = args.log ?? defaultSlackLog;
   const includeReplies = args.options.posts === "all";
+  const includeBotPosts = args.options.includeBotPosts === true;
   const debounceMs = args.options.debounceMs ?? 0;
   const pending = new Map<
     string,
@@ -185,6 +191,27 @@ export function createChannelPostWatcher(args: {
         return skip("thread reply (posts: top-level)", message);
       }
       const botUserId = args.getBotUserId();
+      const author = message.author;
+      if (author?.isBot === true) {
+        if (!includeBotPosts) {
+          return skip("bot-authored post (includeBotPosts off)", message);
+        }
+        const selfBotId = args.getBotId?.();
+        if (selfBotId === undefined && botUserId === undefined) {
+          return skip(
+            "bot-authored post (bot identity unknown; loop safety)",
+            message
+          );
+        }
+        if (
+          (selfBotId !== undefined && author.botId === selfBotId) ||
+          (botUserId !== undefined &&
+            author.userId !== "" &&
+            author.userId === botUserId)
+        ) {
+          return skip("own post (loop safety)", message);
+        }
+      }
       if (botUserId !== undefined && message.text.includes(`<@${botUserId}>`)) {
         return skip("bot mention (app_mention path owns it)", message);
       }

package/src/channels/slack/cursor-account.ts

@@ -114,6 +114,12 @@ export async function dispatchCursorSlackEnvelope(args: {
   envelope: CursorSlackEnvelope;
   send: SendMessageFn;
   host: HostContext;
+  hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
+  isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
+  getContinuationLastBotMessageTs?: (
+    continuationToken: string
+  ) => Promise<string | undefined>;
+  interruptContinuation?: (continuationToken: string) => Promise<boolean>;
 }): Promise<void> {
   const { runtime, envelope } = args;
   const log = runtime.getLog();
@@ -161,6 +167,20 @@ export async function dispatchCursorSlackEnvelope(args: {
     credentials: runtime.credentials,
     host: args.host,
     log,
+    ...(args.hasContinuationSession === undefined
+      ? {}
+      : { hasContinuationSession: args.hasContinuationSession }),
+    ...(args.isContinuationBusy === undefined
+      ? {}
+      : { isContinuationBusy: args.isContinuationBusy }),
+    ...(args.getContinuationLastBotMessageTs === undefined
+      ? {}
+      : {
+          getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
+        }),
+    ...(args.interruptContinuation === undefined
+      ? {}
+      : { interruptContinuation: args.interruptContinuation }),
     ...(envelope.eventId === undefined ? {} : { eventId: envelope.eventId }),
   });
 }

package/src/channels/slack/defaults.ts

@@ -26,28 +26,51 @@ import type {
   SlackSuggestedPrompt,
 } from "./types.js";
 
-const defaultOnInbound: SlackMessageHandler = async (ctx, message) => {
-  await ctx.thread.startTyping("Thinking…");
-  const auth = defaultSlackAuth(message, ctx);
-  return auth === null ? null : { auth };
-};
+function resolveLoadingMessages(
+  loadingMessages: readonly string[] | undefined
+): string[] {
+  if (loadingMessages !== undefined && loadingMessages.length > 0) {
+    return [...loadingMessages];
+  }
+  return [...SLACK_DEFAULT_LOADING_MESSAGES];
+}
 
-export const defaultOnAppMention: SlackMessageHandler = defaultOnInbound;
-export const defaultOnDirectMessage: SlackMessageHandler = defaultOnInbound;
+/** Default mention/DM inbound handler (optional custom loading rotation). */
+export function createDefaultOnInbound(
+  loadingMessages?: readonly string[]
+): SlackMessageHandler {
+  const rotating = resolveLoadingMessages(loadingMessages);
+  return async (ctx, message) => {
+    await ctx.thread.startTyping("Thinking…", rotating);
+    const auth = defaultSlackAuth(message, ctx);
+    return auth === null ? null : { auth };
+  };
+}
 
 /**
- * Default watched-channel-post handler: same thread-scoped principal as
- * mentions (so a later @mention continues the session), tagged with an
- * `engagement: "channel_post"` attribute for auth policies.
+ * Default watched-channel-post handler (optional custom loading rotation).
+ * Same thread-scoped principal as mentions, tagged with
+ * `engagement: "channel_post"` for auth policies.
  */
-export const defaultOnChannelPost: SlackMessageHandler = async (
-  ctx,
-  message
-) => {
-  await ctx.thread.startTyping("Thinking…");
-  const auth = defaultSlackAuth(message, ctx, { engagement: "channel_post" });
-  return auth === null ? null : { auth };
-};
+export function createDefaultOnChannelPost(
+  loadingMessages?: readonly string[]
+): SlackMessageHandler {
+  const rotating = resolveLoadingMessages(loadingMessages);
+  return async (ctx, message) => {
+    await ctx.thread.startTyping("Thinking…", rotating);
+    const auth = defaultSlackAuth(message, ctx, {
+      engagement: "channel_post",
+    });
+    return auth === null ? null : { auth };
+  };
+}
+
+export const defaultOnAppMention: SlackMessageHandler =
+  createDefaultOnInbound();
+export const defaultOnDirectMessage: SlackMessageHandler =
+  createDefaultOnInbound();
+export const defaultOnChannelPost: SlackMessageHandler =
+  createDefaultOnChannelPost();
 
 export interface BuildDefaultEventsOptions {
   credentials?: SlackCredentials;
@@ -55,6 +78,8 @@ export interface BuildDefaultEventsOptions {
   thinkingSteps?: boolean;
   suggestedPrompts?: SlackSuggestedPrompt[];
   suggestedPromptsTitle?: string;
+  /** Rotating assistant status lines; defaults to pack constants. */
+  loadingMessages?: readonly string[];
   /** Resolved per-call so channel onStart can rebind the server logger. */
   getLog?: () => SlackLog;
 }
@@ -74,6 +99,7 @@ export function buildDefaultEvents(
   const thinkingSteps = options.thinkingSteps !== false;
   const suggestedPrompts = options.suggestedPrompts ?? [];
   const suggestedPromptsTitle = options.suggestedPromptsTitle;
+  const loadingMessages = resolveLoadingMessages(options.loadingMessages);
   const botToken = credentials?.botToken;
   const getLog = options.getLog ?? (() => defaultSlackLog);
   const strategy = createStreamDeliveryStrategy({ botToken, getLog });
@@ -87,6 +113,7 @@ export function buildDefaultEvents(
       channel.state.streamTs = null;
       channel.state.streamChannelId = null;
       channel.state.lastPostedText = null;
+      // Keep lastBotMessageTs across turns — warm delta watermark.
       channel.state.approvalMessageByCallId = {};
 
       const state = channel.state;
@@ -106,7 +133,7 @@ export function buildDefaultEvents(
         channelId: state.channelId,
         threadTs: state.threadTs,
         status: "Working…",
-        loadingMessages: [...SLACK_DEFAULT_LOADING_MESSAGES],
+        loadingMessages,
       });
 
       // Retry streaming each turn unless a prior call proved the feature
@@ -178,7 +205,10 @@ export function buildDefaultEvents(
         channelId: channel.state.channelId,
         threadTs: channel.state.threadTs,
         status,
-        loadingMessages: [status, ...SLACK_DEFAULT_LOADING_MESSAGES],
+        loadingMessages: [
+          status,
+          ...loadingMessages.filter((message) => message !== status),
+        ],
       });
       channel.state.lastReasoningTypingAtMs = now;
       channel.state.lastReasoningTypingStatus = status;
@@ -337,6 +367,7 @@ export function buildDefaultEvents(
           threadTs: state.threadTs,
         });
         channel.state.lastPostedText = event.data.text;
+        channel.state.lastBotMessageTs = posted.ts;
         log.info("reply delivered via postMessage", {
           channel: state.channelId,
           thread_ts: state.threadTs,