@cursor/july 0.1.109 → 0.1.112

package/src/channels/slack/placeholder.ts

@@ -0,0 +1,366 @@
+/**
+ * Replaceable first Slack line while the agent is still starting.
+ * The authored static line is posted exactly as declared.
+ * `chat.startStream` then `stopStream` so the line exists and the chip
+ * can paint. An open stream hides `assistant.threads.setStatus`.
+ * The first post-update edits that ts. An unclaimed line is deleted
+ * when the turn ends.
+ */
+
+import { isSlackImChannel } from "../../internal/slack-thread-key.js";
+import {
+  deleteMessage,
+  postMessage,
+  startChatStream,
+  stopChatStream,
+  updateMessage,
+} from "./api.js";
+import { defaultSlackLog, type SlackLog } from "./log.js";
+import type { SlackBotToken } from "./types.js";
+
+type Slot = {
+  claimed: boolean;
+  ts: string | null;
+  streamed: boolean;
+};
+
+type Taken = {
+  ts: string;
+  streamed: boolean;
+};
+
+type PlaceholderLineArgs = {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  threadTs: string;
+  recipientUserId?: string | null;
+  recipientTeamId?: string | null;
+};
+
+const slots = new Map<string, Slot>();
+
+function slotKey(channelId: string, threadTs: string): string {
+  return `${channelId}:${threadTs}`;
+}
+
+function channelKeys(channelId: string): string[] {
+  if (!isSlackImChannel(channelId)) {
+    return [];
+  }
+  const prefix = `${channelId}:`;
+  const keys: string[] = [];
+  for (const key of slots.keys()) {
+    if (key.startsWith(prefix)) {
+      keys.push(key);
+    }
+  }
+  return keys;
+}
+
+export function resetPlaceholderSlots(): void {
+  slots.clear();
+}
+
+function openPlaceholder(key: string): boolean {
+  if (slots.has(key)) {
+    return false;
+  }
+  slots.set(key, { claimed: false, ts: null, streamed: false });
+  return true;
+}
+
+function takePlaceholder(key: string): Taken | undefined {
+  const slot = slots.get(key);
+  if (slot === undefined || slot.claimed) {
+    return undefined;
+  }
+  slot.claimed = true;
+  if (slot.ts === null) {
+    return undefined;
+  }
+  slots.delete(key);
+  return { ts: slot.ts, streamed: slot.streamed };
+}
+
+function rememberPlaceholder(
+  key: string,
+  ts: string,
+  streamed: boolean
+): boolean {
+  const slot = slots.get(key);
+  if (slot === undefined || slot.claimed) {
+    return false;
+  }
+  slot.ts = ts;
+  slot.streamed = streamed;
+  return true;
+}
+
+function closePlaceholder(key: string): Slot | undefined {
+  const slot = slots.get(key);
+  slots.delete(key);
+  return slot;
+}
+
+type FinishArgs = {
+  channelId: string;
+  botToken: SlackBotToken | undefined;
+  log?: SlackLog;
+};
+
+async function retractKey(key: string, args: FinishArgs): Promise<void> {
+  const closed = closePlaceholder(key);
+  if (closed === undefined || closed.claimed || closed.ts === null) {
+    return;
+  }
+  await retractPosted({
+    botToken: args.botToken,
+    channelId: args.channelId,
+    ts: closed.ts,
+    streamed: closed.streamed,
+    log: args.log,
+  });
+}
+
+/** Retract only one thread's slot; admission cleanup must not sweep DM peers. */
+export async function retractPlaceholderSlot(args: {
+  channelId: string;
+  threadTs: string;
+  botToken: SlackBotToken | undefined;
+  log?: SlackLog;
+}): Promise<void> {
+  await retractKey(slotKey(args.channelId, args.threadTs), args);
+}
+
+export async function finishPlaceholder(args: {
+  channelId: string;
+  threadTs: string;
+  botToken: SlackBotToken | undefined;
+  log?: SlackLog;
+}): Promise<void> {
+  const first = slotKey(args.channelId, args.threadTs);
+  await retractKey(first, args);
+  for (const key of channelKeys(args.channelId)) {
+    await retractKey(key, args);
+  }
+}
+
+export function startPlaceholder(args: {
+  line: string;
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  threadTs: string;
+  log?: SlackLog;
+  recipientUserId?: string | null;
+  recipientTeamId?: string | null;
+}): { done: Promise<void>; retract: () => Promise<void> } | undefined {
+  const key = slotKey(args.channelId, args.threadTs);
+  if (!openPlaceholder(key)) {
+    return undefined;
+  }
+  const log = args.log ?? defaultSlackLog;
+  return {
+    done: postPlaceholder({ ...args, key, log }),
+    retract: () => retractKey(key, { ...args, log }),
+  };
+}
+
+/**
+ * Seed the in-process placeholder slot with a control-plane-posted message
+ * ts so the first agentic update overlays that exact Slack message.
+ */
+export type PlaceholderAdoption = "adopted" | "already_adopted" | "occupied";
+
+export function adoptPlaceholder(args: {
+  channelId: string;
+  threadTs: string;
+  ts: string;
+  streamed?: boolean;
+}): PlaceholderAdoption {
+  const key = slotKey(args.channelId, args.threadTs);
+  const existing = slots.get(key);
+  if (
+    existing !== undefined &&
+    !existing.claimed &&
+    existing.ts === args.ts &&
+    existing.streamed === (args.streamed === true)
+  ) {
+    return "already_adopted";
+  }
+  if (!openPlaceholder(key)) {
+    return "occupied";
+  }
+  return rememberPlaceholder(key, args.ts, args.streamed === true)
+    ? "adopted"
+    : "occupied";
+}
+
+/** Delete a control-plane placeholder that this process could not adopt. */
+export async function retractPlaceholderMessage(args: {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  ts: string;
+  streamed: boolean;
+  log?: SlackLog;
+}): Promise<void> {
+  await retractPosted(args);
+}
+
+async function postPlaceholder(args: {
+  line: string;
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  threadTs: string;
+  key: string;
+  log: SlackLog;
+  recipientUserId?: string | null;
+  recipientTeamId?: string | null;
+}): Promise<void> {
+  try {
+    const posted = await postPlaceholderLine(args, args.line);
+    if (rememberPlaceholder(args.key, posted.ts, posted.streamed)) {
+      args.log.info("placeholder posted", {
+        channel: args.channelId,
+        thread_ts: args.threadTs,
+        message_ts: posted.ts,
+        chars: args.line.length,
+      });
+      return;
+    }
+    await retractPosted({
+      botToken: args.botToken,
+      channelId: args.channelId,
+      ts: posted.ts,
+      streamed: posted.streamed,
+      log: args.log,
+    });
+  } catch (error) {
+    args.log.warn(
+      `placeholder post failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      { channel: args.channelId, thread_ts: args.threadTs }
+    );
+    const closed = closePlaceholder(args.key);
+    if (closed === undefined || closed.claimed || closed.ts === null) {
+      return;
+    }
+    await retractPosted({
+      botToken: args.botToken,
+      channelId: args.channelId,
+      ts: closed.ts,
+      streamed: closed.streamed,
+      log: args.log,
+    });
+  }
+}
+
+async function postPlaceholderLine(
+  args: PlaceholderLineArgs,
+  line: string
+): Promise<{ ts: string; streamed: boolean }> {
+  const user = args.recipientUserId;
+  const team = args.recipientTeamId;
+  const started = await startChatStream({
+    botToken: args.botToken,
+    channel: args.channelId,
+    thread_ts: args.threadTs,
+    markdown_text: line,
+    recipient_user_id: user === null || user === "" ? undefined : user,
+    recipient_team_id: team === null || team === "" ? undefined : team,
+  });
+  if (started.ok) {
+    const stopped = await stopChatStream({
+      botToken: args.botToken,
+      channel: args.channelId,
+      ts: started.ts,
+    });
+    return { ts: started.ts, streamed: !stopped.ok };
+  }
+  const posted = await postMessage({
+    botToken: args.botToken,
+    channel: args.channelId,
+    text: line,
+    threadTs: args.threadTs,
+  });
+  return { ts: posted.ts, streamed: false };
+}
+
+export async function overlayPlaceholder(args: {
+  channelId: string;
+  threadTs: string;
+  botToken: SlackBotToken | undefined;
+  text: string;
+}): Promise<string | undefined> {
+  const primary = slotKey(args.channelId, args.threadTs);
+  const painted = await paintSlot(primary, args);
+  for (const key of channelKeys(args.channelId)) {
+    await paintSlot(key, args);
+  }
+  return painted;
+}
+
+async function paintSlot(
+  key: string,
+  args: {
+    botToken: SlackBotToken | undefined;
+    channelId: string;
+    text: string;
+  }
+): Promise<string | undefined> {
+  const taken = takePlaceholder(key);
+  if (taken === undefined) {
+    return undefined;
+  }
+  if (taken.streamed) {
+    await stopChatStream({
+      botToken: args.botToken,
+      channel: args.channelId,
+      ts: taken.ts,
+    });
+  }
+  const result = await updateMessage({
+    botToken: args.botToken,
+    channel: args.channelId,
+    ts: taken.ts,
+    text: args.text,
+  });
+  if (result.ok) {
+    return taken.ts;
+  }
+  await retractPosted({
+    botToken: args.botToken,
+    channelId: args.channelId,
+    ts: taken.ts,
+    streamed: false,
+  });
+  return undefined;
+}
+
+async function retractPosted(args: {
+  botToken: SlackBotToken | undefined;
+  channelId: string;
+  ts: string;
+  streamed: boolean;
+  log?: SlackLog;
+}): Promise<void> {
+  if (args.streamed) {
+    await stopChatStream({
+      botToken: args.botToken,
+      channel: args.channelId,
+      ts: args.ts,
+    });
+  }
+  const result = await deleteMessage({
+    botToken: args.botToken,
+    channel: args.channelId,
+    ts: args.ts,
+  });
+  if (!result.ok) {
+    (args.log ?? defaultSlackLog).warn("placeholder retract failed", {
+      error: result.error,
+      channel: args.channelId,
+      ts: args.ts,
+    });
+  }
+}

package/src/channels/slack/progress-delivery.ts

@@ -1,3 +1,4 @@
+import { markHostedFirstVisibleReply } from "../../internal/hosted-execution-latency.js";
 /**
  * Mid-turn thread progress when `chat.startStream` is unavailable.
  * One editable message; `setThreadStatus` stays on the caller.
@@ -31,7 +32,7 @@ export function createProgressDelivery(
 ): ProgressDelivery {
   const { botToken, getLog } = deps;
 
-  const clear: ProgressDelivery["clear"] = async (args) => {
+  const clear: ProgressDelivery["clear"] = async args => {
     const state = args.channel.state;
     const ts = activeProgressTs(state);
     state.progressTs = null;
@@ -71,6 +72,10 @@ export function createProgressDelivery(
           text: args.text,
         });
         if (updated.ok) {
+          markHostedFirstVisibleReply({
+            outcome: "progress_update",
+            deliverySurface: "slack",
+          });
           return;
         }
         getLog().warn("progress update failed; posting a new message", {
@@ -89,6 +94,10 @@ export function createProgressDelivery(
           text: args.text,
         });
         state.progressTs = posted.ts;
+        markHostedFirstVisibleReply({
+          outcome: "progress_update",
+          deliverySurface: "slack",
+        });
       } catch (error) {
         getLog().warn(
           `progress post failed: ${
@@ -125,6 +134,10 @@ export function createProgressDelivery(
       state.lastPostedText = args.text;
       state.lastBotMessageTs = ts;
       state.progressTs = null;
+      markHostedFirstVisibleReply({
+        outcome: "progress_update",
+        deliverySurface: "slack",
+      });
       return true;
     },
 

package/src/channels/slack/reasoning-chip.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared reasoning-chip throttle for defaults and agentic delivery.
+ * Callers write Slack first, then commit.
+ */
+
+import { truncateTypingStatus } from "./api.js";
+import { firstNonEmptyLine } from "./assistant.js";
+import {
+  SLACK_TYPING_MIN_GROWTH,
+  SLACK_TYPING_MIN_INTERVAL_MS,
+} from "./constants.js";
+import type { SlackChannelState } from "./types.js";
+
+export function nextReasoningChip(
+  state: SlackChannelState,
+  text: string,
+  now: number
+): string | undefined {
+  const line = firstNonEmptyLine(text);
+  if (line === undefined) {
+    return undefined;
+  }
+  const status = truncateTypingStatus(line);
+  const previous = state.lastReasoningTypingStatus;
+  const grew =
+    previous !== null &&
+    status.startsWith(previous) &&
+    status.length >= previous.length + SLACK_TYPING_MIN_GROWTH;
+  const lastAt = state.lastReasoningTypingAtMs;
+  if (
+    !grew &&
+    lastAt !== null &&
+    now - lastAt >= 0 &&
+    now - lastAt < SLACK_TYPING_MIN_INTERVAL_MS
+  ) {
+    return undefined;
+  }
+  return status;
+}
+
+export function commitReasoningChip(
+  state: SlackChannelState,
+  status: string,
+  now: number
+): void {
+  state.lastReasoningTypingAtMs = now;
+  state.lastReasoningTypingStatus = status;
+}

package/src/channels/slack/recording-sink.ts

@@ -0,0 +1,176 @@
+/**
+ * Slack Web API transport that records calls. For evals and tests.
+ */
+
+import type { SlackApiTransport } from "./types.js";
+
+export interface SlackSinkCall {
+  method: string;
+  args: Record<string, unknown>;
+  at: number;
+  ts?: string;
+}
+
+export interface ReadableSinkText {
+  text: string;
+  at: number;
+  method: string;
+}
+
+export interface RecordingSlackSink {
+  transport: SlackApiTransport;
+  calls: SlackSinkCall[];
+  methods(): string[];
+  texts(): string[];
+  firstReadable(): ReadableSinkText | undefined;
+  lastReadable(): ReadableSinkText | undefined;
+  chunks(): unknown[];
+  release(): void;
+}
+
+function readableCall(call: SlackSinkCall): ReadableSinkText | undefined {
+  if (
+    call.method !== "chat.postMessage" &&
+    call.method !== "chat.update" &&
+    call.method !== "chat.startStream" &&
+    call.method !== "chat.appendStream" &&
+    call.method !== "chat.stopStream"
+  ) {
+    return undefined;
+  }
+  const text = textOf(call.args);
+  if (text === "") {
+    return undefined;
+  }
+  return { text, at: call.at, method: call.method };
+}
+
+function firstReadableCall(
+  calls: readonly SlackSinkCall[]
+): ReadableSinkText | undefined {
+  for (const call of calls) {
+    const readable = readableCall(call);
+    if (readable !== undefined) {
+      return readable;
+    }
+  }
+  return undefined;
+}
+
+function lastReadableCall(
+  calls: readonly SlackSinkCall[]
+): ReadableSinkText | undefined {
+  for (let i = calls.length - 1; i >= 0; i--) {
+    const call = calls[i];
+    if (call === undefined) {
+      continue;
+    }
+    const readable = readableCall(call);
+    if (readable !== undefined) {
+      return readable;
+    }
+  }
+  return undefined;
+}
+
+function textOf(args: Record<string, unknown>): string {
+  if (typeof args.markdown_text === "string" && args.markdown_text !== "") {
+    return args.markdown_text;
+  }
+  if (typeof args.text === "string") {
+    return args.text;
+  }
+  return "";
+}
+
+export function createRecordingSlackSink(
+  options: { hold?: boolean | readonly string[] } = {}
+): RecordingSlackSink {
+  const calls: SlackSinkCall[] = [];
+  let n = 0;
+  let releaseHeld: (() => void) | undefined;
+  const holdAll = options.hold === true;
+  const holdMethods = Array.isArray(options.hold)
+    ? new Set(options.hold)
+    : undefined;
+  const gated = holdAll || holdMethods !== undefined;
+  const gate: Promise<void> = gated
+    ? new Promise<void>(resolve => {
+        releaseHeld = resolve;
+      })
+    : Promise.resolve();
+
+  function reply(
+    method: string,
+    args: Record<string, unknown>
+  ): Record<string, unknown> {
+    if (method === "chat.postMessage") {
+      return {
+        ok: true,
+        ts: `${n}.0`,
+        channel: String(args.channel ?? "C1"),
+      };
+    }
+    if (method === "chat.startStream") {
+      return {
+        ok: true,
+        ts: `s${n}.0`,
+        channel: String(args.channel ?? "C1"),
+      };
+    }
+    if (method === "files.getUploadURLExternal") {
+      return {
+        ok: true,
+        upload_url: "https://files.example.test/upload",
+        file_id: `F${n}`,
+      };
+    }
+    if (method === "files.completeUploadExternal") {
+      return { ok: true, files: [] };
+    }
+    if (method === "users.info") {
+      return {
+        ok: true,
+        user: { id: String(args.user ?? "U1"), team_id: "T1" },
+      };
+    }
+    return { ok: true };
+  }
+
+  const transport: SlackApiTransport = {
+    kind: "api-transport",
+    label: "recording",
+    async call(method, args) {
+      n += 1;
+      const result = reply(method, args);
+      const ts = typeof result.ts === "string" ? result.ts : undefined;
+      calls.push({ method, args, at: Date.now(), ts });
+      if (holdAll || holdMethods?.has(method) === true) {
+        await gate;
+      }
+      return result;
+    },
+  };
+  return {
+    transport,
+    calls,
+    methods: () => calls.map(call => call.method),
+    texts: () =>
+      calls
+        .filter(call => readableCall(call) !== undefined)
+        .map(call => textOf(call.args))
+        .filter(text => text !== ""),
+    firstReadable: () => firstReadableCall(calls),
+    lastReadable: () => lastReadableCall(calls),
+    chunks: () =>
+      calls.flatMap(call => {
+        const chunks = call.args.chunks;
+        return Array.isArray(chunks) ? chunks : [];
+      }),
+    release: () => {
+      if (releaseHeld !== undefined) {
+        releaseHeld();
+      }
+    },
+  };
+}