@cursor/july 0.1.1

package/src/channels/slack/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Slack platform channel pack for agent-serve.
+ *
+ * ```ts
+ * import { slackChannel } from "@anysphere/agent-serve/channels/slack";
+ *
+ * // Single agent: SLACK_BOT_TOKEN + SLACK_APP_TOKEN
+ * export default slackChannel();
+ *
+ * // Multi-agent serve: one Slack app per agent
+ * export default slackChannel({ envPrefix: "MY_AGENT" });
+ * // → MY_AGENT_SLACK_BOT_TOKEN + MY_AGENT_SLACK_APP_TOKEN
+ *
+ * // No Slack app at all: ride the signed-in Cursor account's Slack
+ * // connection (`@Cursor <agent name> …` routes here; replies post as
+ * // this agent through the Cursor Slack app)
+ * export default slackChannel({ cursorAccount: true });
+ * ```
+ */
+
+export * from "./api.js";
+export * from "./approvals.js";
+export * from "./assistant.js";
+export * from "./auth.js";
+export * from "./channel-watch.js";
+export * from "./constants.js";
+export * from "./credentials.js";
+export * from "./cursor-account.js";
+export * from "./defaults.js";
+export * from "./dispatch.js";
+export * from "./doctor.js";
+export * from "./event-id-dedupe.js";
+export * from "./inbound.js";
+export * from "./init.js";
+export * from "./interactive.js";
+export * from "./links.js";
+export * from "./log.js";
+export * from "./manifest.js";
+export * from "./pr-ref.js";
+export * from "./setup.js";
+export * from "./slack-channel.js";
+export * from "./socket-mode.js";
+export * from "./stream.js";
+export * from "./tool-approval-events.js";
+export * from "./types.js";

package/src/channels/slack/init.ts

@@ -0,0 +1,133 @@
+/**
+ * Scaffold a Slack channel into an agent-serve project.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { envPrefixFromName, slackEnvKeys } from "./credentials.js";
+import { buildSlackManifestPair } from "./manifest.js";
+
+export interface InitSlackOptions {
+  dir: string;
+  /** Display name for the Slack app. Defaults to directory basename. */
+  name?: string;
+  description?: string;
+  /**
+   * Env prefix for tokens (`MY_AGENT` → `MY_AGENT_SLACK_BOT_TOKEN`). Defaults to
+   * the directory basename so multi-agent serve can mount several Slack bots.
+   * Pass `""` to use the shared `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` globals.
+   */
+  envPrefix?: string;
+  /**
+   * Subscribe the generated manifests to `message.channels` +
+   * `message.groups` for the opt-in channel watch
+   * (`engagement.channelPosts` on `slackChannel`).
+   */
+  channelPosts?: boolean;
+}
+
+export interface InitSlackResult {
+  rootDir: string;
+  files: string[];
+  envPrefix: string | undefined;
+  envKeys: { bot: string; app: string };
+}
+
+export async function initSlackChannel(
+  options: InitSlackOptions
+): Promise<InitSlackResult> {
+  const rootDir = resolve(options.dir);
+  const name = options.name ?? basename(rootDir);
+  const envPrefix =
+    options.envPrefix === ""
+      ? undefined
+      : (options.envPrefix ?? envPrefixFromName(basename(rootDir)));
+  const envKeys = slackEnvKeys(envPrefix);
+  const written: string[] = [];
+
+  const write = async (rel: string, contents: string): Promise<void> => {
+    const abs = join(rootDir, rel);
+    await mkdir(join(abs, ".."), { recursive: true });
+    await writeFile(abs, contents, { flag: "wx" });
+    written.push(rel);
+  };
+
+  const envPrefixLine =
+    envPrefix === undefined
+      ? ""
+      : `  envPrefix: ${JSON.stringify(envPrefix)},\n`;
+
+  await write(
+    "agent/channels/slack.ts",
+    `import { slackChannel } from "@anysphere/agent-serve/channels/slack";
+
+/**
+ * Slack channel (Socket Mode).
+ *
+ * Tokens: ${envKeys.bot} + ${envKeys.app}
+ * (see .agent-serve/slack/env.example).
+ *
+ * Full setup: agent-serve slack setup
+ */
+export default slackChannel({
+${envPrefixLine}  // Streaming and thinking steps default to true.
+  suggestedPrompts: [
+    { title: "Help", message: "How can you help me?" },
+    { title: "Status", message: "What are you working on?" },
+  ],
+});
+`
+  );
+
+  const pair = buildSlackManifestPair({
+    name,
+    ...(options.description === undefined
+      ? {}
+      : { description: options.description }),
+    ...(options.channelPosts === true ? { channelPosts: true } : {}),
+  });
+
+  await write(
+    ".agent-serve/slack/manifest.dev.json",
+    `${JSON.stringify(pair.dev, null, 2)}\n`
+  );
+  await write(
+    ".agent-serve/slack/manifest.prod.json",
+    `${JSON.stringify(pair.prod, null, 2)}\n`
+  );
+
+  await write(
+    ".agent-serve/slack/env.example",
+    `# Copy to .env.local (or export in your shell). Use the *dev* Slack app
+# for local development; use the Prod app tokens in deployment secrets.
+#
+# Multi-agent serve needs a distinct Slack app (and token pair) per agent.
+
+${envKeys.bot}=xoxb-...
+${envKeys.app}=xapp-...
+`
+  );
+
+  await write(
+    ".agent-serve/slack/setup-status.json",
+    `${JSON.stringify(
+      {
+        updatedAt: new Date().toISOString(),
+        envPrefix: envPrefix ?? null,
+        envKeys,
+        phases: {
+          generate: true,
+          createApps: false,
+          install: false,
+          env: false,
+          serve: false,
+          smoke: false,
+        },
+      },
+      null,
+      2
+    )}\n`
+  );
+
+  return { rootDir, files: written, envPrefix, envKeys };
+}

package/src/channels/slack/interactive.ts

@@ -0,0 +1,194 @@
+/**
+ * Socket Mode interactive payloads (Block Kit Approve/Deny).
+ */
+
+import type {
+  ApprovalDecision,
+  AuthContext,
+  ChannelSession,
+  PendingApproval,
+} from "../../types.js";
+import { decisionFromActionId, parseApprovalActionValue } from "./approvals.js";
+import { buildSlackInteractiveApprovalAuth } from "./auth.js";
+import { defaultSlackLog, type SlackLog } from "./log.js";
+import type { SlackCredentials } from "./types.js";
+
+export interface SlackInteractiveDispatchDeps {
+  credentials: SlackCredentials | undefined;
+  getSession: (sessionId: string) => Promise<ChannelSession | null>;
+  resolveApproval: (
+    sessionId: string,
+    callId: string,
+    decision: ApprovalDecision,
+    auth: AuthContext | null
+  ) => Promise<PendingApproval>;
+  waitUntil: (promise: Promise<unknown>) => void;
+  log?: SlackLog;
+}
+
+/**
+ * Handle a Socket Mode `interactive` body. Returns true when this was
+ * an agent-serve approval action (handled or rejected with a reason).
+ */
+export async function dispatchInteractiveFromPayload(
+  payload: unknown,
+  deps: SlackInteractiveDispatchDeps
+): Promise<boolean> {
+  const log = deps.log ?? defaultSlackLog;
+  const parsed = parseBlockActionsPayload(payload);
+  if (parsed === null) {
+    return false;
+  }
+
+  const decision = decisionFromActionId(parsed.actionId);
+  const value = parseApprovalActionValue(parsed.value);
+  if (decision === null || value === null) {
+    return false;
+  }
+
+  log.info("interactive approval", {
+    decision,
+    session: value.sessionId,
+    call_id: value.callId,
+    user: parsed.userId,
+    channel: parsed.channelId,
+  });
+
+  const session = await deps.getSession(value.sessionId);
+  if (session === null) {
+    log.warn("interactive approval: unknown session", {
+      session: value.sessionId,
+    });
+    return true;
+  }
+
+  const attrs = session.info.auth?.attributes ?? {};
+  const sessionChannel = attrs.channel_id ?? "";
+  const sessionThread = attrs.thread_ts ?? "";
+  if (
+    sessionChannel !== "" &&
+    parsed.channelId !== "" &&
+    sessionChannel !== parsed.channelId
+  ) {
+    log.warn("interactive approval: channel mismatch", {
+      session: value.sessionId,
+      expected: sessionChannel,
+      got: parsed.channelId,
+    });
+    return true;
+  }
+  if (
+    sessionThread !== "" &&
+    parsed.threadTs !== "" &&
+    sessionThread !== parsed.threadTs
+  ) {
+    log.warn("interactive approval: thread mismatch", {
+      session: value.sessionId,
+      expected: sessionThread,
+      got: parsed.threadTs,
+    });
+    return true;
+  }
+
+  const sessionAuth = session.info.auth;
+  if (sessionAuth === undefined || sessionAuth === null) {
+    log.warn("interactive approval: session has no auth", {
+      session: value.sessionId,
+    });
+    return true;
+  }
+
+  const teamId = attrs.team_id;
+  const clickingAuth = buildSlackInteractiveApprovalAuth({
+    sessionAuth,
+    channelId: parsed.channelId || sessionChannel,
+    threadTs: parsed.threadTs || sessionThread,
+    ...(teamId === undefined || teamId === "" ? {} : { teamId }),
+    clickingUserId: parsed.userId,
+  });
+
+  try {
+    await deps.resolveApproval(
+      value.sessionId,
+      value.callId,
+      decision,
+      clickingAuth
+    );
+  } catch (error) {
+    log.warn("interactive approval resolve failed", {
+      session: value.sessionId,
+      call_id: value.callId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+  return true;
+}
+
+interface ParsedBlockAction {
+  actionId: string;
+  value: string;
+  channelId: string;
+  threadTs: string;
+  userId: string;
+  messageTs: string;
+}
+
+function parseBlockActionsPayload(payload: unknown): ParsedBlockAction | null {
+  if (typeof payload !== "object" || payload === null) {
+    return null;
+  }
+  const record = payload as Record<string, unknown>;
+  if (record.type !== "block_actions") {
+    return null;
+  }
+  const actions = record.actions;
+  if (!Array.isArray(actions) || actions.length === 0) {
+    return null;
+  }
+  const first = actions[0];
+  if (typeof first !== "object" || first === null) {
+    return null;
+  }
+  const action = first as Record<string, unknown>;
+  if (
+    typeof action.action_id !== "string" ||
+    typeof action.value !== "string"
+  ) {
+    return null;
+  }
+
+  const channel =
+    typeof record.channel === "object" && record.channel !== null
+      ? (record.channel as Record<string, unknown>)
+      : {};
+  const message =
+    typeof record.message === "object" && record.message !== null
+      ? (record.message as Record<string, unknown>)
+      : {};
+  const user =
+    typeof record.user === "object" && record.user !== null
+      ? (record.user as Record<string, unknown>)
+      : {};
+
+  const channelId = typeof channel.id === "string" ? channel.id : "";
+  const messageTs = typeof message.ts === "string" ? message.ts : "";
+  const threadTs =
+    typeof message.thread_ts === "string"
+      ? message.thread_ts
+      : typeof record.container === "object" &&
+          record.container !== null &&
+          typeof (record.container as { thread_ts?: unknown }).thread_ts ===
+            "string"
+        ? (record.container as { thread_ts: string }).thread_ts
+        : messageTs;
+  const userId = typeof user.id === "string" ? user.id : "";
+
+  return {
+    actionId: action.action_id,
+    value: action.value,
+    channelId,
+    threadTs,
+    userId,
+    messageTs,
+  };
+}

package/src/channels/slack/links.ts

@@ -0,0 +1,23 @@
+/**
+ * Slack deep links for threads / messages.
+ */
+
+/** Build a web permalink that opens a Slack thread in the browser. */
+export function slackThreadPermalink(args: {
+  channelId: string;
+  threadTs: string;
+  teamId?: string;
+}): string | null {
+  const channelId = args.channelId.trim();
+  const threadTs = args.threadTs.trim();
+  if (channelId === "" || threadTs === "") {
+    return null;
+  }
+  const teamId = args.teamId?.trim();
+  if (teamId !== undefined && teamId !== "" && teamId !== "unknown") {
+    // Client deep link opens the thread pane in the right workspace.
+    return `https://app.slack.com/client/${encodeURIComponent(teamId)}/${encodeURIComponent(channelId)}/thread/${encodeURIComponent(channelId)}-${encodeURIComponent(threadTs)}`;
+  }
+  const pTs = `p${threadTs.replace(".", "")}`;
+  return `https://app.slack.com/archives/${encodeURIComponent(channelId)}/${pTs}?thread_ts=${encodeURIComponent(threadTs)}`;
+}

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

@@ -0,0 +1,201 @@
+/**
+ * Live-reply delivery for Slack `chat.startStream` / append / stop.
+ *
+ * Cursor-account channels do not use this path — they reply with a single
+ * final `chat.postMessage` and put thinking on `assistant.threads.setStatus`
+ * (no message edits).
+ */
+
+import type { ChannelEventContext } from "../../types.js";
+import { appendChatStream, startChatStream, stopChatStream } from "./api.js";
+import type { SlackLog } from "./log.js";
+import { computeStreamAppend } from "./stream.js";
+import type { SlackBotToken, SlackChannelState } from "./types.js";
+
+type SlackChannel = ChannelEventContext<SlackChannelState>;
+
+export interface LiveDeliveryDeps {
+  botToken: SlackBotToken | undefined;
+  getLog: () => SlackLog;
+}
+
+/**
+ * How the default handlers deliver an in-progress reply. Methods write live
+ * delivery state (`streamTs`, `streamChannelId`, `lastPostedText`,
+ * `streamingUnavailable`) on `channel.state` directly.
+ */
+export interface LiveDeliveryStrategy {
+  /** True when tool-call thinking steps can be appended to the live message. */
+  readonly inlineToolSteps: boolean;
+  /** Open the live message (stream start). */
+  start(args: {
+    channel: SlackChannel;
+    channelId: string;
+    threadTs: string;
+    sessionId: string;
+  }): Promise<void>;
+  /** Push the latest cumulative text to the live message (throttled). */
+  append(args: {
+    channel: SlackChannel;
+    channelId: string;
+    streamTs: string;
+    text: string;
+    sessionId: string;
+  }): Promise<void>;
+  /**
+   * Flush the final reply text. `delivered` is false only when the caller must
+   * post the full reply as a fresh message (finalize failed on partial text).
+   */
+  finalize(args: {
+    channel: SlackChannel;
+    channelId: string;
+    streamTs: string;
+    text: string;
+    sessionId: string;
+  }): Promise<{ delivered: boolean }>;
+  /** Close the live message when the turn produced no final text. */
+  finalizeEmpty(args: {
+    channel: SlackChannel;
+    channelId: string;
+    streamTs: string;
+  }): Promise<void>;
+  /** Best-effort remove a live message left open after the turn ended. */
+  cleanupOrphan(args: { channel: SlackChannel }): Promise<void>;
+  /** Deliver the error text into the live message; `delivered` gates a fallback post. */
+  fail(args: {
+    channel: SlackChannel;
+    channelId: string;
+    streamTs: string;
+    errorText: string;
+    sessionId: string;
+  }): Promise<{ delivered: boolean }>;
+}
+
+export function createStreamDeliveryStrategy(
+  deps: LiveDeliveryDeps
+): LiveDeliveryStrategy {
+  const { botToken, getLog } = deps;
+  return {
+    inlineToolSteps: true,
+
+    async start({ channel, channelId, threadTs, sessionId }) {
+      const log = getLog();
+      const started = await startChatStream({
+        botToken,
+        channel: channelId,
+        thread_ts: threadTs,
+        markdown_text: "",
+      });
+      if (!started.ok) {
+        log.warn("chat.startStream unavailable", {
+          error: started.error,
+          channel: channelId,
+          thread_ts: threadTs,
+          session: sessionId,
+        });
+        if (started.unsupported === true) {
+          channel.state.streamingUnavailable = true;
+        }
+        return;
+      }
+      channel.state.streamTs = started.ts;
+      channel.state.streamChannelId = started.channel;
+      channel.state.lastPostedText = "";
+      log.info("chat.startStream ok", {
+        channel: started.channel,
+        stream_ts: started.ts,
+        session: sessionId,
+      });
+    },
+
+    async append({ channel, channelId, streamTs, text, sessionId }) {
+      const appendText = computeStreamAppend(
+        channel.state.lastPostedText,
+        text
+      );
+      if (appendText === "") {
+        return;
+      }
+      const result = await appendChatStream({
+        botToken,
+        channel: channelId,
+        ts: streamTs,
+        markdown_text: appendText,
+      });
+      if (!result.ok) {
+        getLog().warn("appendStream failed", {
+          error: result.error,
+          channel: channelId,
+          stream_ts: streamTs,
+          session: sessionId,
+        });
+        if (result.unsupported === true) {
+          channel.state.streamingUnavailable = true;
+        }
+        return;
+      }
+      channel.state.lastPostedText = text;
+    },
+
+    async finalize({ channel, channelId, streamTs, text, sessionId }) {
+      const log = getLog();
+      // Only send the unsent suffix — full text was already appended.
+      const appendText = computeStreamAppend(
+        channel.state.lastPostedText,
+        text
+      );
+      const stopped = await stopChatStream({
+        botToken,
+        channel: channelId,
+        ts: streamTs,
+        markdown_text: appendText === "" ? undefined : appendText,
+      });
+      if (stopped.ok) {
+        channel.state.streamTs = null;
+        channel.state.lastPostedText = text;
+        log.info("reply delivered via stream", {
+          channel: channelId,
+          stream_ts: streamTs,
+          session: sessionId,
+          chars: text.length,
+        });
+        return { delivered: true };
+      }
+      log.warn("chat.stopStream failed; falling back to postMessage", {
+        error: stopped.error,
+        channel: channelId,
+        stream_ts: streamTs,
+        session: sessionId,
+      });
+      if (stopped.unsupported === true) {
+        channel.state.streamingUnavailable = true;
+      }
+      channel.state.streamTs = null;
+      // If we already streamed content, do not post the full reply again.
+      const alreadyStreamed =
+        typeof channel.state.lastPostedText === "string" &&
+        channel.state.lastPostedText.length > 0;
+      return { delivered: alreadyStreamed };
+    },
+
+    async finalizeEmpty({ channelId, streamTs }) {
+      await stopChatStream({ botToken, channel: channelId, ts: streamTs });
+    },
+
+    async cleanupOrphan() {
+      // The stream path closes its message in message.completed / turn.failed;
+      // there is nothing to clean up after turn.completed.
+    },
+
+    async fail({ channel, channelId, streamTs, errorText }) {
+      const stopped = await stopChatStream({
+        botToken,
+        channel: channelId,
+        ts: streamTs,
+        markdown_text: errorText,
+      });
+      channel.state.streamTs = null;
+      return { delivered: stopped.ok };
+    },
+  };
+}

package/src/channels/slack/log.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared logging for the Slack channel pack.
+ *
+ * Uses the same `(line: string) => void` contract as ServeOptions.logger.
+ * Lines always start with `[agent-serve/slack]` so Socket Mode docs and greps
+ * keep working. Optional key=value fields carry correlation ids.
+ */
+
+export type SlackLogWrite = (line: string) => void;
+
+export type SlackLogLevel = "debug" | "info" | "warn" | "error";
+
+export type SlackLogFields = Record<
+  string,
+  string | number | boolean | null | undefined
+>;
+
+export interface SlackLog {
+  /** Raw sink used by Socket Mode (already-prefixed lines ok). */
+  write: SlackLogWrite;
+  debug: (message: string, fields?: SlackLogFields) => void;
+  info: (message: string, fields?: SlackLogFields) => void;
+  warn: (message: string, fields?: SlackLogFields) => void;
+  error: (message: string, fields?: SlackLogFields) => void;
+}
+
+/** Format `key=value` pairs; omit null/undefined. */
+export function formatSlackLogFields(fields?: SlackLogFields): string {
+  if (fields === undefined) {
+    return "";
+  }
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+    const rendered =
+      typeof value === "string" && /[\s=]/.test(value)
+        ? JSON.stringify(value)
+        : String(value);
+    parts.push(`${key}=${rendered}`);
+  }
+  return parts.length === 0 ? "" : ` ${parts.join(" ")}`;
+}
+
+export function formatSlackLogLine(
+  level: SlackLogLevel,
+  message: string,
+  fields?: SlackLogFields
+): string {
+  const levelTag = level === "info" ? "" : `${level} `;
+  return `[agent-serve/slack] ${levelTag}${message}${formatSlackLogFields(fields)}`;
+}
+
+export function createSlackLogger(
+  write: SlackLogWrite = (line) => console.log(line)
+): SlackLog {
+  const emit = (
+    level: SlackLogLevel,
+    message: string,
+    fields?: SlackLogFields
+  ): void => {
+    write(formatSlackLogLine(level, message, fields));
+  };
+
+  return {
+    write(line: string): void {
+      // Preserve Socket Mode messages that already include the prefix.
+      write(
+        line.startsWith("[agent-serve/slack]")
+          ? line
+          : `[agent-serve/slack] ${line}`
+      );
+    },
+    debug: (message, fields) => emit("debug", message, fields),
+    info: (message, fields) => emit("info", message, fields),
+    warn: (message, fields) => emit("warn", message, fields),
+    error: (message, fields) => emit("error", message, fields),
+  };
+}
+
+/** Default logger when none is injected (console). */
+export const defaultSlackLog: SlackLog = createSlackLogger();