@cursor/july 0.1.7 → 0.1.9

package/src/channels/slack/nudge-carrier.ts

@@ -0,0 +1,182 @@
+/**
+ * Harness-side nudge carrier: a small Cursor hooks.json + script that drains
+ * the durable Slack nudge store at tool boundaries (MCP / builtin tools).
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export const SLACK_NUDGE_ROOT_REL = ".agent-serve/slack-nudge-root";
+export const SLACK_NUDGE_CONTINUATION_REL =
+  ".agent-serve/slack-nudge-continuation";
+export const SLACK_NUDGE_CARRIER_REL = ".agent-serve/slack-nudge-carrier.mjs";
+
+/** Carrier script body — reads nudge-root + continuation, drains pending. */
+export const SLACK_NUDGE_CARRIER_SCRIPT: string = `#!/usr/bin/env node
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const workspace = dirname(here);
+
+function safeKey(value) {
+  const trimmed = String(value ?? "").trim();
+  if (trimmed === "" || trimmed === "." || trimmed === "..") return "_empty";
+  const sanitized = trimmed
+    .replace(/[^a-zA-Z0-9._-]+/g, "_")
+    .replace(/^\\.+/, "")
+    .replace(/\\.+/g, "_")
+    .slice(0, 180);
+  if (sanitized === "" || sanitized === "." || sanitized === "..") return "_empty";
+  return sanitized;
+}
+
+async function readText(rel) {
+  try {
+    return (await readFile(join(workspace, rel), "utf8")).trim();
+  } catch {
+    return "";
+  }
+}
+
+async function main() {
+  const root = await readText(${JSON.stringify(SLACK_NUDGE_ROOT_REL)});
+  const continuation = await readText(
+    ${JSON.stringify(SLACK_NUDGE_CONTINUATION_REL)}
+  );
+  if (root === "" || continuation === "") {
+    process.stdout.write("{}\\n");
+    return;
+  }
+  const pendingDir = join(root, safeKey(continuation), "pending");
+  const deliveredDir = join(root, safeKey(continuation), "delivered");
+  let names = [];
+  try {
+    names = await readdir(pendingDir);
+  } catch {
+    process.stdout.write("{}\\n");
+    return;
+  }
+  const nudges = [];
+  await mkdir(deliveredDir, { recursive: true });
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const pendingPath = join(pendingDir, name);
+    let record;
+    try {
+      record = JSON.parse(await readFile(pendingPath, "utf8"));
+    } catch {
+      continue;
+    }
+    const sourceTs = typeof record.sourceTs === "string" ? record.sourceTs : "";
+    if (sourceTs === "") continue;
+    const dest = join(deliveredDir, safeKey(sourceTs));
+    try {
+      await readFile(dest, "utf8");
+      await rm(pendingPath, { force: true });
+      continue;
+    } catch {
+      // not delivered yet
+    }
+    const tmp = dest + "." + process.pid + ".tmp";
+    try {
+      await writeFile(tmp, JSON.stringify(record) + "\\n", "utf8");
+      await rename(tmp, dest);
+      await rm(pendingPath, { force: true });
+      nudges.push(record);
+    } catch {
+      await rm(tmp, { force: true }).catch(() => {});
+      await rm(pendingPath, { force: true }).catch(() => {});
+    }
+  }
+  if (nudges.length === 0) {
+    process.stdout.write("{}\\n");
+    return;
+  }
+  const lines = [
+    "<slack_followup>",
+    "New Slack follow-up(s) arrived while you were working. Incorporate them before your final reply. If an ask was already answered in-thread, ack briefly instead of re-answering.",
+    "",
+  ];
+  for (const nudge of nudges) {
+    const who =
+      typeof nudge.author === "string" && nudge.author !== ""
+        ? nudge.author
+        : "someone";
+    lines.push("- " + who + " @ " + nudge.sourceTs + ":");
+    lines.push(
+      typeof nudge.text === "string" && nudge.text.trim() !== ""
+        ? nudge.text.trim()
+        : "(empty)"
+    );
+    lines.push("");
+  }
+  lines.push("</slack_followup>");
+  process.stdout.write(
+    JSON.stringify({ additional_context: lines.join("\\n").trimEnd() }) + "\\n"
+  );
+}
+
+main().catch(() => {
+  process.stdout.write("{}\\n");
+});
+`;
+
+type HooksConfig = {
+  version?: number;
+  hooks?: Record<string, Array<{ command: string; failClosed?: boolean }>>;
+};
+
+/**
+ * Write carrier script + pointer files and ensure pre/postToolUse hooks invoke it.
+ * Safe to call every turn (idempotent overwrite of carrier + pointers).
+ */
+export async function materializeSlackNudgeCarrier(args: {
+  harnessCwd: string;
+  nudgeRootDir: string;
+  continuationKey: string;
+}): Promise<void> {
+  if (args.continuationKey.trim() === "") {
+    return;
+  }
+  await mkdir(join(args.harnessCwd, ".agent-serve"), { recursive: true });
+  await mkdir(join(args.harnessCwd, ".cursor"), { recursive: true });
+  await writeFile(
+    join(args.harnessCwd, SLACK_NUDGE_ROOT_REL),
+    `${args.nudgeRootDir}\n`,
+    "utf8"
+  );
+  await writeFile(
+    join(args.harnessCwd, SLACK_NUDGE_CONTINUATION_REL),
+    `${args.continuationKey}\n`,
+    "utf8"
+  );
+  await writeFile(
+    join(args.harnessCwd, SLACK_NUDGE_CARRIER_REL),
+    SLACK_NUDGE_CARRIER_SCRIPT,
+    "utf8"
+  );
+
+  const hooksPath = join(args.harnessCwd, ".cursor", "hooks.json");
+  let existing: HooksConfig = { version: 1, hooks: {} };
+  try {
+    existing = JSON.parse(await readFile(hooksPath, "utf8")) as HooksConfig;
+  } catch {
+    // fresh
+  }
+  const hooks = { ...(existing.hooks ?? {}) };
+  const command = `node ${SLACK_NUDGE_CARRIER_REL}`;
+  for (const step of ["preToolUse", "postToolUse"] as const) {
+    const list = [...(hooks[step] ?? [])].filter(
+      (entry) => !entry.command.includes("slack-nudge-carrier")
+    );
+    list.push({ command, failClosed: false });
+    hooks[step] = list;
+  }
+  const next: HooksConfig = {
+    version: existing.version ?? 1,
+    hooks,
+  };
+  await writeFile(hooksPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+}

package/src/channels/slack/nudge-store.ts

@@ -0,0 +1,308 @@
+/**
+ * Durable Slack follow-up nudge store (Benny-style).
+ *
+ * Mid-turn inject and boundary resume share one exactly-once contract:
+ * pending nudges rename into delivered/ keyed by source message ts.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+
+export interface SlackNudgeRecord {
+  id: string;
+  continuationKey: string;
+  sourceTs: string;
+  text: string;
+  author?: string;
+  createdAt: string;
+  /** Content hash for pending dedupe. */
+  contentHash: string;
+}
+
+export interface SlackNudgeAppendInput {
+  continuationKey: string;
+  sourceTs: string;
+  text: string;
+  author?: string;
+}
+
+/**
+ * Map an arbitrary key onto a single path segment under the store root.
+ * Rejects empty / `.` / `..` and strips remaining dots so path traversal
+ * cannot escape `<stateRoot>/slack-nudges` (or `slack-asks`).
+ */
+function safeKey(continuationKey: string): string {
+  const trimmed = continuationKey.trim();
+  if (trimmed === "" || trimmed === "." || trimmed === "..") {
+    return "_empty";
+  }
+  const sanitized = trimmed
+    .replace(/[^a-zA-Z0-9._-]+/g, "_")
+    .replace(/^\.+/, "")
+    .replace(/\.+/g, "_")
+    .slice(0, 180);
+  if (sanitized === "" || sanitized === "." || sanitized === "..") {
+    return "_empty";
+  }
+  return sanitized;
+}
+
+function contentHash(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+function newNudgeId(): string {
+  return `nudge_${randomBytes(8).toString("hex")}`;
+}
+
+export function formatSlackFollowupNudgeBlock(
+  nudges: readonly SlackNudgeRecord[]
+): string | undefined {
+  if (nudges.length === 0) {
+    return undefined;
+  }
+  const lines = [
+    "<slack_followup>",
+    "New Slack follow-up(s) arrived while you were working. Incorporate them before your final reply. If an ask was already answered in-thread, ack briefly instead of re-answering.",
+    "",
+  ];
+  for (const nudge of nudges) {
+    const who =
+      nudge.author === undefined || nudge.author === ""
+        ? "someone"
+        : nudge.author;
+    lines.push(`- ${who} @ ${nudge.sourceTs}:`);
+    lines.push(nudge.text.trim() === "" ? "(empty)" : nudge.text.trim());
+    lines.push("");
+  }
+  lines.push("</slack_followup>");
+  return lines.join("\n").trimEnd();
+}
+
+/**
+ * Filesystem nudge store under `<root>/<continuation>/pending|delivered`.
+ */
+export class SlackNudgeStore {
+  private readonly rootDir: string;
+
+  constructor(rootDir: string) {
+    this.rootDir = rootDir;
+  }
+
+  private continuationDir(continuationKey: string): string {
+    return join(this.rootDir, safeKey(continuationKey));
+  }
+
+  private pendingDir(continuationKey: string): string {
+    return join(this.continuationDir(continuationKey), "pending");
+  }
+
+  private deliveredDir(continuationKey: string): string {
+    return join(this.continuationDir(continuationKey), "delivered");
+  }
+
+  private deliveredPath(continuationKey: string, sourceTs: string): string {
+    return join(this.deliveredDir(continuationKey), safeKey(sourceTs));
+  }
+
+  async append(input: SlackNudgeAppendInput): Promise<boolean> {
+    const continuationKey = input.continuationKey.trim();
+    const sourceTs = input.sourceTs.trim();
+    const text = input.text.trim();
+    if (continuationKey === "" || sourceTs === "" || text === "") {
+      return false;
+    }
+    if (await this.isDelivered(continuationKey, sourceTs)) {
+      return false;
+    }
+    const pending = await this.listPending(continuationKey);
+    const hash = contentHash(text);
+    if (
+      pending.some(
+        (item) => item.sourceTs === sourceTs || item.contentHash === hash
+      )
+    ) {
+      return false;
+    }
+    const record: SlackNudgeRecord = {
+      id: newNudgeId(),
+      continuationKey,
+      sourceTs,
+      text,
+      ...(input.author === undefined || input.author === ""
+        ? {}
+        : { author: input.author }),
+      createdAt: new Date().toISOString(),
+      contentHash: hash,
+    };
+    const dir = this.pendingDir(continuationKey);
+    await mkdir(dir, { recursive: true });
+    const target = join(dir, `${record.id}.json`);
+    const tmp = `${target}.${process.pid}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(record)}\n`, "utf8");
+    await rename(tmp, target);
+    return true;
+  }
+
+  async listPending(continuationKey: string): Promise<SlackNudgeRecord[]> {
+    const dir = this.pendingDir(continuationKey);
+    let names: string[];
+    try {
+      names = await readdir(dir);
+    } catch {
+      return [];
+    }
+    const records: SlackNudgeRecord[] = [];
+    for (const name of names) {
+      if (!name.endsWith(".json")) {
+        continue;
+      }
+      try {
+        const raw = await readFile(join(dir, name), "utf8");
+        const parsed = JSON.parse(raw) as SlackNudgeRecord;
+        if (
+          typeof parsed.id === "string" &&
+          typeof parsed.sourceTs === "string" &&
+          typeof parsed.text === "string"
+        ) {
+          records.push(parsed);
+        }
+      } catch {
+        // Skip corrupt pending files.
+      }
+    }
+    records.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    return records;
+  }
+
+  async isDelivered(
+    continuationKey: string,
+    sourceTs: string
+  ): Promise<boolean> {
+    if (continuationKey.trim() === "" || sourceTs.trim() === "") {
+      return false;
+    }
+    try {
+      await readFile(this.deliveredPath(continuationKey, sourceTs), "utf8");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async hasUndelivered(continuationKey: string): Promise<boolean> {
+    return (await this.listPending(continuationKey)).length > 0;
+  }
+
+  /**
+   * Atomically move all pending nudges to delivered and return them.
+   * Already-delivered source ts values are dropped (exactly-once).
+   */
+  async drainForInject(continuationKey: string): Promise<SlackNudgeRecord[]> {
+    const pending = await this.listPending(continuationKey);
+    if (pending.length === 0) {
+      return [];
+    }
+    await mkdir(this.deliveredDir(continuationKey), { recursive: true });
+    const delivered: SlackNudgeRecord[] = [];
+    for (const record of pending) {
+      const pendingPath = join(
+        this.pendingDir(continuationKey),
+        `${record.id}.json`
+      );
+      if (await this.isDelivered(continuationKey, record.sourceTs)) {
+        await rm(pendingPath, { force: true });
+        continue;
+      }
+      const dest = this.deliveredPath(continuationKey, record.sourceTs);
+      const tmp = `${dest}.${process.pid}.tmp`;
+      try {
+        await writeFile(tmp, `${JSON.stringify(record)}\n`, "utf8");
+        await rename(tmp, dest);
+        await rm(pendingPath, { force: true });
+        delivered.push(record);
+      } catch {
+        await rm(tmp, { force: true }).catch(() => {});
+        // Race: another drain won — treat as delivered.
+        await rm(pendingPath, { force: true }).catch(() => {});
+      }
+    }
+    return delivered;
+  }
+
+  async clear(continuationKey: string): Promise<void> {
+    await rm(this.continuationDir(continuationKey), {
+      recursive: true,
+      force: true,
+    });
+  }
+
+  /** Drain + format for tool/hook inject. */
+  async drainFormatted(continuationKey: string): Promise<string | undefined> {
+    return formatSlackFollowupNudgeBlock(
+      await this.drainForInject(continuationKey)
+    );
+  }
+}
+
+/**
+ * Durable ask claim store: one marker per `channelId:message.ts` so delayed
+ * Slack redelivery cannot start a second full answer.
+ */
+export class SlackAskDedupeStore {
+  private readonly rootDir: string;
+
+  constructor(rootDir: string) {
+    this.rootDir = rootDir;
+  }
+
+  private markerPath(channelId: string, messageTs: string): string {
+    return join(
+      this.rootDir,
+      `${safeKey(channelId)}__${safeKey(messageTs)}.claimed`
+    );
+  }
+
+  /** Returns true the first time this ask is claimed. */
+  async tryClaim(channelId: string, messageTs: string): Promise<boolean> {
+    if (channelId.trim() === "" || messageTs.trim() === "") {
+      return false;
+    }
+    const path = this.markerPath(channelId, messageTs);
+    await mkdir(this.rootDir, { recursive: true });
+    try {
+      await writeFile(path, `${new Date().toISOString()}\n`, {
+        encoding: "utf8",
+        flag: "wx",
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Drop a claim so a failed delivery can be retried. */
+  async release(channelId: string, messageTs: string): Promise<void> {
+    if (channelId.trim() === "" || messageTs.trim() === "") {
+      return;
+    }
+    await rm(this.markerPath(channelId, messageTs), { force: true });
+  }
+
+  async wasClaimed(channelId: string, messageTs: string): Promise<boolean> {
+    try {
+      await readFile(this.markerPath(channelId, messageTs), "utf8");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

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

@@ -35,9 +35,8 @@ import {
 } from "./cursor-account.js";
 import {
   buildDefaultEvents,
-  defaultOnAppMention,
-  defaultOnChannelPost,
-  defaultOnDirectMessage,
+  createDefaultOnChannelPost,
+  createDefaultOnInbound,
 } from "./defaults.js";
 import {
   dispatchInboundFromEventBody,
@@ -130,9 +129,12 @@ export function slackChannel<const Name extends string = string>(
       ? { botToken: accountTransport }
       : (options.credentials ?? credentialsFromEnv(options.envPrefix));
   const envKeys = slackEnvKeys(options.envPrefix);
-  const onAppMention = options.onAppMention ?? defaultOnAppMention;
-  const onDirectMessage = options.onDirectMessage ?? defaultOnDirectMessage;
-  const onChannelPost = options.onChannelPost ?? defaultOnChannelPost;
+  const loadingMessages = options.loadingMessages;
+  const defaultInbound = createDefaultOnInbound(loadingMessages);
+  const onAppMention = options.onAppMention ?? defaultInbound;
+  const onDirectMessage = options.onDirectMessage ?? defaultInbound;
+  const onChannelPost =
+    options.onChannelPost ?? createDefaultOnChannelPost(loadingMessages);
   const engagement = options.engagement ?? {};
   const mentionsEnabled = engagement.mentions !== false;
   const directMessagesEnabled = engagement.directMessages !== false;
@@ -167,6 +169,7 @@ export function slackChannel<const Name extends string = string>(
         thinkingSteps: options.thinkingSteps,
         suggestedPrompts: options.suggestedPrompts,
         suggestedPromptsTitle: options.suggestedPromptsTitle,
+        loadingMessages,
         getLog,
       })
     );
@@ -183,6 +186,12 @@ export function slackChannel<const Name extends string = string>(
     send: SendMessageFn;
     waitUntil: (promise: Promise<unknown>) => void;
     host: HostContext;
+    hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
+    isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
+    getContinuationLastBotMessageTs?: (
+      continuationToken: string
+    ) => Promise<string | undefined>;
+    interruptContinuation?: (continuationToken: string) => Promise<boolean>;
   }): SlackInboundDispatchDeps {
     return {
       send: args.send,
@@ -195,6 +204,21 @@ export function slackChannel<const Name extends string = string>(
       log: getLog(),
       mentionsEnabled,
       directMessagesEnabled,
+      ...(args.hasContinuationSession === undefined
+        ? {}
+        : { hasContinuationSession: args.hasContinuationSession }),
+      ...(args.isContinuationBusy === undefined
+        ? {}
+        : { isContinuationBusy: args.isContinuationBusy }),
+      ...(args.getContinuationLastBotMessageTs === undefined
+        ? {}
+        : {
+            getContinuationLastBotMessageTs:
+              args.getContinuationLastBotMessageTs,
+          }),
+      ...(args.interruptContinuation === undefined
+        ? {}
+        : { interruptContinuation: args.interruptContinuation }),
       ...(channelWatch === undefined ? {} : { channelWatch }),
     };
   }
@@ -237,6 +261,7 @@ export function slackChannel<const Name extends string = string>(
 
       return send(input.message, {
         auth: input.auth,
+        admission: "coalesce",
         continuationToken: slackContinuationKey(channelId, threadTs),
         state: emptySlackChannelState({
           channelId,
@@ -271,12 +296,15 @@ export function slackChannel<const Name extends string = string>(
       if (channelPosts !== undefined) {
         const allowlist = new SlackChannelAllowlist(channelPosts.allow);
         let botUserId: string | undefined;
+        let botId: string | undefined;
         try {
           const { WebClient } = await import("@slack/web-api");
           const client = new WebClient(botToken);
           const identity = await client.auth.test();
           botUserId =
             typeof identity.user_id === "string" ? identity.user_id : undefined;
+          botId =
+            typeof identity.bot_id === "string" ? identity.bot_id : undefined;
           const names = allowlist.unresolvedNames();
           if (names.length > 0) {
             allowlist.applyResolvedNames(
@@ -288,31 +316,62 @@ export function slackChannel<const Name extends string = string>(
             error: error instanceof Error ? error.message : String(error),
           });
         }
-        channelWatch = createChannelPostWatcher({
-          options: channelPosts,
-          allowlist,
-          getBotUserId: () => botUserId,
-          log: getLog(),
-          dispatch: (message, eventId) => {
-            args.waitUntil(
-              dispatchInboundMessage({
-                kind: "channel_post",
-                message,
-                handler: onChannelPost,
-                send: args.send,
-                credentials,
-                host: args.host,
-                log: getLog(),
-                ...(eventId === undefined ? {} : { eventId }),
-              })
-            );
-          },
-        });
-        getLog().info("channel watch enabled", {
-          channels: channelPosts.allow.join(","),
-          posts: channelPosts.posts ?? "top-level",
-          debounce_ms: channelPosts.debounceMs ?? 0,
-        });
+        if (
+          channelPosts.includeBotPosts === true &&
+          botUserId === undefined &&
+          botId === undefined
+        ) {
+          getLog().error("channel watch disabled", {
+            reason:
+              "includeBotPosts requires bot identity from auth.test (loop safety)",
+          });
+        } else {
+          channelWatch = createChannelPostWatcher({
+            options: channelPosts,
+            allowlist,
+            getBotUserId: () => botUserId,
+            getBotId: () => botId,
+            log: getLog(),
+            dispatch: (message, eventId) => {
+              args.waitUntil(
+                dispatchInboundMessage({
+                  kind: "channel_post",
+                  message,
+                  handler: onChannelPost,
+                  send: args.send,
+                  credentials,
+                  host: args.host,
+                  log: getLog(),
+                  ...(args.hasContinuationSession === undefined
+                    ? {}
+                    : {
+                        hasContinuationSession: args.hasContinuationSession,
+                      }),
+                  ...(args.isContinuationBusy === undefined
+                    ? {}
+                    : { isContinuationBusy: args.isContinuationBusy }),
+                  ...(args.getContinuationLastBotMessageTs === undefined
+                    ? {}
+                    : {
+                        getContinuationLastBotMessageTs:
+                          args.getContinuationLastBotMessageTs,
+                      }),
+                  ...(args.interruptContinuation === undefined
+                    ? {}
+                    : {
+                        interruptContinuation: args.interruptContinuation,
+                      }),
+                  ...(eventId === undefined ? {} : { eventId }),
+                })
+              );
+            },
+          });
+          getLog().info("channel watch enabled", {
+            channels: channelPosts.allow.join(","),
+            posts: channelPosts.posts ?? "top-level",
+            debounce_ms: channelPosts.debounceMs ?? 0,
+          });
+        }
       }
 
       const socketOptions: SlackSocketModeOptions = {
@@ -325,6 +384,21 @@ export function slackChannel<const Name extends string = string>(
               send: args.send,
               waitUntil: args.waitUntil,
               host: args.host,
+              ...(args.hasContinuationSession === undefined
+                ? {}
+                : { hasContinuationSession: args.hasContinuationSession }),
+              ...(args.isContinuationBusy === undefined
+                ? {}
+                : { isContinuationBusy: args.isContinuationBusy }),
+              ...(args.getContinuationLastBotMessageTs === undefined
+                ? {}
+                : {
+                    getContinuationLastBotMessageTs:
+                      args.getContinuationLastBotMessageTs,
+                  }),
+              ...(args.interruptContinuation === undefined
+                ? {}
+                : { interruptContinuation: args.interruptContinuation }),
             })
           );
         },
@@ -366,6 +440,7 @@ export function slackChannel<const Name extends string = string>(
       channelWatch = undefined;
       await socketHandle?.stop();
       socketHandle = null;
+      await options.onStop?.();
     },
   });