@cursor/july 0.1.109 → 0.1.112

package/src/extensions/slack-communication/evals/slack-placeholder.eval.ts

@@ -0,0 +1,194 @@
+import { defineEval, type EvalDefinition, equals } from "../../../evals.js";
+import {
+  chipStatuses,
+  countMethod,
+  firstCall,
+  JENNY_ACK,
+  netPosted,
+  playAgentic,
+  playHostedPlaceholder,
+  playPlaceholder,
+  publish,
+  startInbound,
+  uniqueTexts,
+} from "./harness.js";
+
+const PLACEHOLDER = "Ok, checking…";
+
+const slackPlaceholderEval: EvalDefinition = defineEval({
+  description:
+    "Static agentic Slack placeholder posting, overlay, retract, and follow-up behavior.",
+  cases: [
+    {
+      id: "placeholder-then-replace",
+      description:
+        "The authored line is the first readable text. The first post-update edits that same timestamp, and a later update is a new message.",
+      async test(t) {
+        const off = await playPlaceholder({
+          agentDelayMs: 40,
+          steps: [...publish("Found the leak."), { type: "turn.completed" }],
+        });
+        const on = await playPlaceholder({
+          placeholder: PLACEHOLDER,
+          waitForPlaceholder: true,
+          agentDelayMs: 40,
+          steps: [
+            ...publish("Found the leak."),
+            ...publish("Also the test."),
+            { type: "turn.completed" },
+          ],
+        });
+        t.check(off.first?.text, equals("Found the leak."));
+        t.check(on.first?.text, equals(PLACEHOLDER));
+        t.check(on.last?.text, equals("Also the test."));
+        t.check(countMethod(on.sink, "chat.startStream"), equals(1));
+        t.check(countMethod(on.sink, "chat.stopStream"), equals(1));
+        t.check(countMethod(on.sink, "chat.postMessage"), equals(1));
+        t.check(countMethod(on.sink, "chat.update"), equals(1));
+        t.check(
+          firstCall(on.sink, "chat.update")?.args.ts,
+          equals(firstCall(on.sink, "chat.startStream")?.ts)
+        );
+        t.check(
+          firstCall(on.sink, "chat.update")?.args.markdown_text,
+          equals("Found the leak.")
+        );
+        t.check(
+          uniqueTexts(on.sink),
+          equals([PLACEHOLDER, "Found the leak.", "Also the test."])
+        );
+      },
+    },
+    {
+      id: "placeholder-chip-after-stop",
+      description:
+        "The placeholder stream closes before tool status paints the chip.",
+      async test(t) {
+        const play = await playPlaceholder({
+          placeholder: PLACEHOLDER,
+          waitForPlaceholder: true,
+          steps: [
+            {
+              type: "message.completed",
+              text: "Querying Datadog.",
+              finishReason: "tool_call",
+            },
+            {
+              type: "actions.requested",
+              calls: [{ tool: "Datadog", id: "d1" }],
+            },
+            ...publish("Found the leak."),
+            { type: "turn.completed" },
+          ],
+        });
+        const stop = play.sink.calls.findIndex(
+          call => call.method === "chat.stopStream"
+        );
+        const chip = play.sink.calls.findIndex(
+          call =>
+            call.method === "assistant.threads.setStatus" &&
+            call.args.status === "Querying Datadog."
+        );
+        t.check(stop >= 0, equals(true));
+        t.check(chip > stop, equals(true));
+        t.check(
+          chipStatuses(play.sink).includes("Querying Datadog."),
+          equals(true)
+        );
+      },
+    },
+    {
+      id: "placeholder-retracted-if-silent",
+      description:
+        "A static placeholder that the agent never claims is deleted when the turn ends.",
+      async test(t) {
+        const play = await playPlaceholder({
+          placeholder: PLACEHOLDER,
+          waitForPlaceholder: true,
+          steps: [{ type: "turn.started" }, { type: "turn.completed" }],
+        });
+        t.check(play.first?.text, equals(PLACEHOLDER));
+        t.check(countMethod(play.sink, "chat.update"), equals(0));
+        t.check(countMethod(play.sink, "chat.delete"), equals(1));
+        t.check(netPosted(play.sink), equals(0));
+      },
+    },
+    {
+      id: "placeholder-hosted-posts-on-turn",
+      description:
+        "Hosted admission posts nothing. Execution uses the authored static line and the first post-update overlays it.",
+      async test(t) {
+        const play = await playHostedPlaceholder({
+          placeholder: PLACEHOLDER,
+          steps: [
+            ...publish("Found the leak."),
+            ...publish("Also the test."),
+            { type: "turn.completed" },
+          ],
+        });
+        t.check(play.admittedPosts, equals(0));
+        t.check(play.first?.text, equals(PLACEHOLDER));
+        t.check(play.last?.text, equals("Also the test."));
+        t.check(countMethod(play.sink, "chat.startStream"), equals(1));
+        t.check(countMethod(play.sink, "chat.update"), equals(1));
+        t.check(countMethod(play.sink, "chat.delete"), equals(0));
+      },
+    },
+    {
+      id: "placeholder-coalesced-followup-overlays",
+      description:
+        "A coalesced follow-up gets a new static placeholder that the next agent update overlays.",
+      async test(t) {
+        const first = startInbound({
+          ack: JENNY_ACK,
+          channelId: "C1",
+          ts: "1.1",
+          threadTs: "1.0",
+          placeholder: PLACEHOLDER,
+        });
+        await first.done;
+        await playAgentic(
+          [...publish("Found the leak."), { type: "turn.completed" }],
+          {
+            sink: first.sink,
+            channelId: "C1",
+            startPainted: true,
+            placeholder: PLACEHOLDER,
+          }
+        );
+        const second = startInbound({
+          ack: JENNY_ACK,
+          channelId: "C1",
+          ts: "1.2",
+          threadTs: "1.0",
+          placeholder: PLACEHOLDER,
+          coalesced: true,
+          sink: first.sink,
+        });
+        await second.done;
+        await playAgentic(
+          [...publish("Also the timeout."), { type: "turn.completed" }],
+          {
+            sink: first.sink,
+            channelId: "C1",
+            startPainted: true,
+            placeholder: PLACEHOLDER,
+          }
+        );
+        const streams = first.sink.calls.filter(
+          call => call.method === "chat.startStream"
+        );
+        const updates = first.sink.calls.filter(
+          call => call.method === "chat.update"
+        );
+        t.check(streams.length, equals(2));
+        t.check(updates.length, equals(2));
+        t.check(updates[0]?.args.ts, equals(streams[0]?.ts));
+        t.check(updates[1]?.args.ts, equals(streams[1]?.ts));
+        t.check(updates[1]?.args.markdown_text, equals("Also the timeout."));
+      },
+    },
+  ],
+});
+
+export default slackPlaceholderEval;

package/src/extensions/slack-communication/extension.ts

@@ -0,0 +1,45 @@
+/**
+ * Tools and voice so an agent can own Slack outbound in agentic mode.
+ *
+ * ```ts
+ * // agent/extensions/slack.ts
+ * import slackCommunication from "@cursor/july/extensions/slack-communication";
+ *
+ * export default slackCommunication();
+ * // export default slackCommunication({ tone: "Lead with the merge decision." });
+ * ```
+ *
+ * Pair with `slackChannel({ reply: { mode: "agentic" } })`. The channel
+ * acks the parent (`reply.ack`, default `eyes`) and paints the status
+ * chip from turn hooks and `actions.requested` (not model `set-status`).
+ * It watches `post-update`,
+ * `post-file`, `post-card`, `react`, `edit-message`, and
+ * `delete-message` (bare or `<namespace>__<name>`) and renders them
+ * through the channel Slack client. The tools do not call Slack.
+ * `post-update` returns a ts for edit and delete.
+ */
+
+import { z } from "zod";
+import { defineExtension } from "../../extensions.js";
+import type { Extension } from "../../types.js";
+
+export interface SlackCommunicationOptions {
+  /** Extra voice, appended to `slack-voice`. */
+  tone?: string;
+}
+
+const slackCommunication: Extension<
+  SlackCommunicationOptions,
+  SlackCommunicationOptions | undefined
+> = defineExtension({
+  root: import.meta.dirname,
+  description:
+    "Tools and voice so an agent can own Slack outbound when the channel is agentic.",
+  config: z
+    .object({
+      tone: z.string().trim().min(1).optional(),
+    })
+    .default({}),
+});
+
+export default slackCommunication;

package/src/extensions/slack-communication/skills/slack-voice.ts

@@ -0,0 +1,59 @@
+import { prompt } from "../../../prompt.js";
+import { defineSkill } from "../../../skills.js";
+import type { SkillDefinition } from "../../../types.js";
+import extension from "../extension.js";
+
+export const DEFAULT_VOICE: string = prompt`
+  # Slack voice
+
+  You own this thread. Humans only see what you post through the Slack tools.
+
+  Lead with the result. Write complete sentences. Do not narrate every tool call.
+
+  The channel acks the parent and paints thinking on the status chip. Do not react to ack. Do not set-status for thinking.
+
+  If the turn will take more than a glance, a one-line post-update is the first tool, before investigation.
+
+  A multi-step investigate also posts the dead-end or widen and the breakthrough. Open plus a late dump is not enough. Tools stay off the thread. The channel paints them on the chip.
+
+  ## post-update
+
+  A new message in the thread. Mid-turn: when the picture changed and a reader should know. Final: a new message. Do not rewrite a previous line. The result includes ts. Pass that ts to edit-message or delete-message.
+
+  ## post-card
+
+  A collapsible task card (id, title, details, status). Same id updates in place. That is progress. Do not use it as the reply.
+
+  ## post-file
+
+  Attach a workspace file to the reply. Evidence, not text you could have written.
+
+  ## react
+
+  Emoji on a message ts. Omit ts to react to the thread root. Later reactions for a real reason. The channel already acked.
+
+  ## set-status
+
+  The channel owns the thinking chip. Do not write thinking here.
+
+  ## edit-message
+
+  Correct a fact already posted (wrong number, wrong link). ts is the one post-update returned. Not a narrative rewrite.
+
+  ## delete-message
+
+  A message this turn just posted that is wrong (duplicate, secret, wrong thread). ts is the one post-update returned. Short reason. Never delete to clean up progress. Never delete someone else's message.
+
+  Do not also write the reply as assistant text. The channel ignores that in agentic mode.
+`;
+
+const tone = extension.config.tone;
+const slackVoice: SkillDefinition = defineSkill({
+  description: "How to write Slack updates in this thread.",
+  markdown:
+    tone === undefined || tone === ""
+      ? DEFAULT_VOICE
+      : `${DEFAULT_VOICE}\n\n${tone}`,
+});
+
+export default slackVoice;

package/src/extensions/slack-communication/tools/delete-message.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { has } from "../../../channels/slack/agentic-posted.js";
+import { MAX_REASON_CHARS } from "../../../channels/slack/agentic-signals.js";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+
+const INVALID_ARGUMENTS_MESSAGE =
+  "delete-message needs a ts this turn posted and a short reason.";
+const FOREIGN_TS = "ts is not a message this turn posted";
+
+const deleteMessage: ToolDefinition = defineTool({
+  description: [
+    "Delete a message this turn just posted that is wrong (duplicate, secret, wrong thread).",
+    "ts is the one post-update returned. Never someone else's message.",
+    "Never delete to clean up progress.",
+    "The channel watching this turn deletes it.",
+  ].join(" "),
+  inputSchema: z.object({
+    ts: z.string().trim().min(1, INVALID_ARGUMENTS_MESSAGE),
+    reason: z
+      .string()
+      .trim()
+      .min(1, INVALID_ARGUMENTS_MESSAGE)
+      .max(MAX_REASON_CHARS, INVALID_ARGUMENTS_MESSAGE),
+  }),
+  execute: ({ ts, reason }, ctx) => {
+    if (!has(ctx.session.id, ts)) {
+      return FOREIGN_TS;
+    }
+    return { ts, reason };
+  },
+});
+
+export default deleteMessage;

package/src/extensions/slack-communication/tools/edit-message.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { has } from "../../../channels/slack/agentic-posted.js";
+import { MAX_UPDATE_CHARS } from "../../../channels/slack/agentic-signals.js";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+
+const INVALID_ARGUMENTS_MESSAGE =
+  "edit-message needs a ts this turn posted and a non-empty message.";
+const FOREIGN_TS = "ts is not a message this turn posted";
+
+const editMessage: ToolDefinition = defineTool({
+  description: [
+    "Correct a fact on a message this turn already posted (wrong number, wrong link).",
+    "ts is the one post-update returned. Not a rewrite of the reply.",
+    "The channel watching this turn applies the edit.",
+  ].join(" "),
+  inputSchema: z.object({
+    ts: z.string().trim().min(1, INVALID_ARGUMENTS_MESSAGE),
+    message: z
+      .string({
+        required_error: INVALID_ARGUMENTS_MESSAGE,
+        invalid_type_error: INVALID_ARGUMENTS_MESSAGE,
+      })
+      .min(1, INVALID_ARGUMENTS_MESSAGE)
+      .superRefine((message, ctx) => {
+        if (message.length > MAX_UPDATE_CHARS) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `size (${message.length}) is more than ${MAX_UPDATE_CHARS}-character limit. drop what the reader would not act on and try again`,
+          });
+        }
+      }),
+  }),
+  execute: ({ ts, message }, ctx) => {
+    if (!has(ctx.session.id, ts)) {
+      return FOREIGN_TS;
+    }
+    return { ts, message };
+  },
+});
+
+export default editMessage;

package/src/extensions/slack-communication/tools/post-card.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+
+const postCard: ToolDefinition = defineTool({
+  description: [
+    "Publish or update a collapsible task card in the thread.",
+    "Same id updates the same card. That is progress.",
+    "status is pending, in_progress, complete, or error.",
+    "Use a card for work that should stay on screen and change.",
+    "Do not use it as the reply; that is post-update.",
+    "The tool records nothing. The channel watching this turn renders the card.",
+  ].join(" "),
+  inputSchema: z.object({
+    id: z.string().trim().min(1),
+    title: z.string().trim().min(1),
+    status: z.enum(["pending", "in_progress", "complete", "error"]),
+    details: z.string().trim().min(1).optional(),
+  }),
+  execute: ({ id, title, status, details }) => ({
+    id,
+    title,
+    status,
+    details,
+  }),
+});
+
+export default postCard;

package/src/extensions/slack-communication/tools/post-file.ts

@@ -0,0 +1,85 @@
+import { realpathSync, statSync } from "node:fs";
+import { basename, extname, isAbsolute, sep } from "node:path";
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+
+const ALLOWED = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".svg",
+  ".pdf",
+  ".html",
+  ".txt",
+  ".log",
+  ".json",
+  ".csv",
+  ".md",
+  ".mp4",
+  ".mov",
+  ".webm",
+]);
+
+const MAX_BYTES = 50 * 1024 * 1024;
+
+function human(bytes: number): string {
+  return bytes < 1024 * 1024
+    ? `${Math.round(bytes / 1024)} KB`
+    : `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+const postFile: ToolDefinition = defineTool({
+  description: [
+    "Attach a file to the final reply.",
+    "Nothing is posted when you call this: the file is staged, and everything",
+    "staged is uploaded once, after the reply.",
+    "Use it for evidence worth keeping, not for text you could write in the reply.",
+  ].join(" "),
+  inputSchema: z.object({
+    path: z
+      .string()
+      .min(1)
+      .describe(
+        "Absolute path to the file. Relative paths are rejected: this runs on the host, not in the agent shell."
+      ),
+  }),
+  execute: ({ path }, ctx) => {
+    if (!isAbsolute(path)) {
+      return `Refused: "${path}" is not absolute. Give the full path.`;
+    }
+    let realPath: string;
+    try {
+      realPath = realpathSync(path);
+    } catch {
+      return `No such file: ${path}`;
+    }
+    const workspaceRoot = realpathSync(ctx.workspaceDir);
+    if (
+      realPath !== workspaceRoot &&
+      !realPath.startsWith(`${workspaceRoot}${sep}`)
+    ) {
+      return `Refused: ${path} is outside ${ctx.workspaceDir}. Copy it into your workspace first.`;
+    }
+    const extension = extname(realPath).toLowerCase();
+    if (!ALLOWED.has(extension)) {
+      return `Refused: ${extension || "no extension"} is not a type Slack renders. Allowed: ${[...ALLOWED].join(", ")}.`;
+    }
+    const info = statSync(realPath);
+    if (!info.isFile()) {
+      return `Refused: ${path} is not a file.`;
+    }
+    if (info.size > MAX_BYTES) {
+      return `Refused: ${human(info.size)} is over the ${human(MAX_BYTES)} upload cap.`;
+    }
+    return {
+      path: realPath,
+      name: basename(realPath),
+      workspace: workspaceRoot,
+    };
+  },
+});
+
+export default postFile;

package/src/extensions/slack-communication/tools/post-update.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { reserve } from "../../../channels/slack/agentic-posted.js";
+import { MAX_UPDATE_CHARS } from "../../../channels/slack/agentic-signals.js";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+
+const INVALID_ARGUMENTS_MESSAGE =
+  "post-update needs a non-empty message string.";
+
+const postUpdate: ToolDefinition = defineTool({
+  description: [
+    "Post a new message in this thread.",
+    "Mid-turn: when the picture changed and a reader should know.",
+    "Final: a new message. Do not rewrite a previous line.",
+    "If the turn will take more than a glance, call this first.",
+    "The result includes ts. Pass that ts to edit-message or delete-message.",
+    "The channel watching this turn posts the message.",
+  ].join(" "),
+  inputSchema: z.object({
+    message: z
+      .string({
+        required_error: INVALID_ARGUMENTS_MESSAGE,
+        invalid_type_error: INVALID_ARGUMENTS_MESSAGE,
+      })
+      .min(1, INVALID_ARGUMENTS_MESSAGE)
+      .superRefine((message, ctx) => {
+        if (message.length > MAX_UPDATE_CHARS) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `size (${message.length}) is more than ${MAX_UPDATE_CHARS}-character limit. drop what the reader would not act on and move receipts into a post-file attachment, rather than compressing the sentences you keep, and try again`,
+          });
+        }
+      }),
+  }),
+  execute: ({ message }, ctx) => ({
+    message,
+    ts: reserve(ctx.session.id),
+  }),
+});
+
+export default postUpdate;

package/src/extensions/slack-communication/tools/react.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { emojiName } from "../../../channels/slack/agentic-signals.js";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+
+const react: ToolDefinition = defineTool({
+  description: [
+    "Add an emoji reaction to a message in this thread.",
+    "emoji is a Slack name without a leading colon, or :name:.",
+    "ts is the message timestamp. Omit it to react to the thread root.",
+    "The tool records nothing. The channel watching this turn adds the reaction.",
+  ].join(" "),
+  inputSchema: z.object({
+    emoji: z
+      .string()
+      .trim()
+      .min(1)
+      .refine(
+        value => emojiName(value) !== undefined,
+        "emoji must be a Slack reaction name"
+      ),
+    ts: z.string().trim().min(1).optional(),
+  }),
+  execute: ({ emoji, ts }) => {
+    const name = emojiName(emoji);
+    if (name === undefined) {
+      return "emoji must be a Slack reaction name";
+    }
+    return { emoji: name, ts };
+  },
+});
+
+export default react;

package/src/extensions/slack-communication/tools/set-status.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { SLACK_STATUS_MAX_LEN } from "../../../channels/slack/constants.js";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+
+const setStatus: ToolDefinition = defineTool({
+  description: [
+    "Set the status line under this thread (assistant.threads.setStatus).",
+    "That is the subtitle chip, not a message.",
+    `Keep it under ${String(SLACK_STATUS_MAX_LEN)} characters.`,
+    "Pass an empty string to clear it.",
+    "The channel paints thinking on this chip from the turn. Do not use this for thinking.",
+    "The tool records nothing. The channel watching this turn writes the chip.",
+  ].join(" "),
+  inputSchema: z.object({
+    status: z.string().max(SLACK_STATUS_MAX_LEN),
+  }),
+  execute: ({ status }) => ({ status }),
+});
+
+export default setStatus;