Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

20.0 KB
Raw Blame
import { errMessage, swallowAs } from "../util/errors.ts";
import { safeChunks, safeClip } from "./safe-cut.ts";
import { sleep } from "./util.ts";
import { isExternallyShared, isMpim, type ChannelMeta } from "./identity.ts";

export interface SlackReplyArgs {
  channel: string;
  text: string;
  thread_ts?: string;
  reply_broadcast?: false;
  username?: string;
  icon_emoji?: string;
  unfurl_links?: boolean;
  unfurl_media?: boolean;
}

export interface BotIdentityOverride {
  username?: string;
  icon_emoji?: string;
}

export function botIdentityFromEnv(env: Record<string, string | undefined>): BotIdentityOverride {
  const username = (env.SLACK_BOT_DISPLAY_NAME ?? "").trim();
  const icon_emoji = (env.SLACK_BOT_ICON_EMOJI ?? "").trim();
  return {
    ...(username ? { username } : {}),
    ...(icon_emoji ? { icon_emoji } : {}),
  };
}

let defaultIdentity: BotIdentityOverride = {};
export function setDefaultBotIdentity(identity: BotIdentityOverride | undefined): void {
  defaultIdentity = identity ?? {};
}

export function botIdentityArgs(): BotIdentityOverride {
  const id = defaultIdentity;
  return {
    ...(id.username ? { username: id.username } : {}),
    ...(id.icon_emoji ? { icon_emoji: id.icon_emoji } : {}),
  };
}

export function slackReplyArgs(
  channel: string,
  text: string,
  threadTs: string | undefined,
  opts: { threadOnly?: boolean; unfurlLinks?: boolean } = {},
): SlackReplyArgs {
  return {
    channel,
    text,
    ...(threadTs ? { thread_ts: threadTs } : {}),
    ...(threadTs && opts.threadOnly ? { reply_broadcast: false as const } : {}),
    ...(opts.unfurlLinks !== undefined ? { unfurl_links: opts.unfurlLinks, unfurl_media: opts.unfurlLinks } : {}),
    ...botIdentityArgs(),
  };
}

export function scopeSurfaceUrl(webUiPublicUrl: string | undefined, scopeId: string): string | undefined {
  const base = (webUiPublicUrl ?? "").trim().replace(/\/+$/, "");
  if (!base || !scopeId) return undefined;
  const personal = /^personal:([^@]+)@/.exec(scopeId);
  if (personal?.[1] && /^[a-z0-9._-]+$/i.test(personal[1])) return `${base}/projects/${personal[1].toLowerCase()}`;
  const shared = /^(channel|group):(.+)$/.exec(scopeId);
  if (shared?.[1] && shared[2]) return `${base}/projects/${shared[1]}/${encodeURIComponent(shared[2])}`;
  return `${base}/contexts?scope=${encodeURIComponent(scopeId)}`;
}

export function channelSurfaceUrl(webUiPublicUrl: string | undefined, channelId: string): string | undefined {
  return scopeSurfaceUrl(webUiPublicUrl, `channel:${channelId}`);
}

export function channelWelcomeMessage(surfaceUrl: string | undefined): string {
  if (!surfaceUrl) {
    return "QM here, ready to assist.";
  }
  return `QM here, ready to assist. Access my data and channel settings <${surfaceUrl}|here>.`;
}

export function surfaceHeaderText(facts: { modelName?: string }, projectUrl: string | undefined): string | undefined {
  const model = (facts.modelName ?? "").trim();
  const url = (projectUrl ?? "").trim();
  const modelText = model ? `Using ${model} here.` : "";
  const link = url ? `<${url}|More settings>` : "";
  return [modelText, link].filter(Boolean).join(" ") || undefined;
}

function unwrapSlackLinks(text: string): string {
  return text.replace(/<([^<>|]+)(?:\|[^<>]*)?>/g, "$1");
}

export function headerUpdate(
  existing: { value?: string; creator?: string } | undefined,
  botUserId: string,
  desired: string,
): "set" | "skip" {
  const value = (existing?.value ?? "").trim();
  if (unwrapSlackLinks(value) === unwrapSlackLinks(desired)) return "skip";
  if (!value) return "set";
  return existing?.creator === botUserId ? "set" : "skip";
}

const SURFACE_HEADER_MAX_TRACKED = 1000;

export interface SurfaceHeaderClient {
  chat: {
    postMessage: (args: SlackReplyArgs) => Promise<{ ts?: string }>;
    update: (args: { channel: string; ts: string; text: string }) => Promise<unknown>;
    delete: (args: { channel: string; ts: string }) => Promise<unknown>;
  };
  pins: {
    list: (args: { channel: string }) => Promise<{ items?: PinnedItem[] }>;
    add: (args: { channel: string; timestamp: string }) => Promise<unknown>;
    remove: (args: { channel: string; timestamp: string }) => Promise<unknown>;
  };
  conversations: {
    info: (args: { channel: string }) => Promise<{ channel?: ChannelMeta }>;
    setTopic: (args: { channel: string; topic: string }) => Promise<unknown>;
  };
}

export interface PinnedItem {
  message?: { ts?: string; user?: string; text?: string };
}

export function isSurfaceHeaderMessage(text: string | undefined): boolean {
  const t = (text ?? "").trim();
  if (!t) return false;
  return /^(Using .+ here\.)?\s*(<[^<>|]+\|More settings>)?$/.test(t);
}

export function findHeaderPin(
  items: PinnedItem[] | undefined,
  botUserId: string,
): { ts: string; text: string } | undefined {
  for (const item of items ?? []) {
    const m = item.message;
    if (m?.ts && m.user === botUserId && isSurfaceHeaderMessage(m.text)) return { ts: m.ts, text: m.text ?? "" };
  }
  return undefined;
}

const HEADER_PIN_OFF = "<surface-header-off>";

export function createSurfaceHeaderEnsurer(opts: {
  headerFacts(scope: string): Promise<{ agentLabel?: string; modelName: string }>;
  channelPinEnabled?(scope: string): Promise<boolean>;
  webUiPublicUrl: string | undefined;
  ids: { botUserId: string };
  maxTracked?: number;
}): (
  client: SurfaceHeaderClient,
  channel: string,
  scopeId: string,
  kind: "dm" | "channel",
  ensureOpts?: { pinNew?: boolean },
) => void {
  const maxTracked = opts.maxTracked ?? SURFACE_HEADER_MAX_TRACKED;
  const settled = new Map<string, string>();
  const inFlight = new Set<string>();
  const requeued = new Map<string, { pinNew?: boolean }>();
  return function ensure(client, channel, scopeId, kind, ensureOpts) {
    if (inFlight.has(channel)) {
      const prior = requeued.get(channel);
      requeued.set(channel, { pinNew: Boolean(prior?.pinNew) || Boolean(ensureOpts?.pinNew) });
      return;
    }
    inFlight.add(channel);
    void (async () => {
      try {
        const desired = surfaceHeaderText(
          await opts.headerFacts(scopeId),
          scopeSurfaceUrl(opts.webUiPublicUrl, scopeId),
        );
        if (!desired) return;
        const enabled = kind === "dm" || ((await opts.channelPinEnabled?.(scopeId)) ?? false);
        const goal = enabled ? desired : HEADER_PIN_OFF;
        if (settled.get(channel) === goal) return;
        const info = (await client.conversations.info({ channel })).channel;
        if (kind === "dm") {
          if (headerUpdate(info?.topic, opts.ids.botUserId, desired) === "set")
            await client.conversations.setTopic({ channel, topic: desired });
        } else {
          if (isExternallyShared(info) || isMpim(info)) return;
          const pinned = findHeaderPin((await client.pins.list({ channel })).items, opts.ids.botUserId);
          if (!enabled) {
            if (pinned) {
              await client.pins.remove({ channel, timestamp: pinned.ts });
              await client.chat.delete({ channel, ts: pinned.ts });
            }
          } else if (pinned) {
            if (unwrapSlackLinks(pinned.text) !== unwrapSlackLinks(desired))
              await client.chat.update({ channel, ts: pinned.ts, text: desired });
          } else if (ensureOpts?.pinNew) {
            const posted = await client.chat.postMessage(
              slackReplyArgs(channel, desired, undefined, { unfurlLinks: false }),
            );
            if (posted.ts) await client.pins.add({ channel, timestamp: posted.ts });
          }
        }
        settled.set(channel, goal);
        capMap(settled, maxTracked);
      } catch (err) {
        console.error("[slack] surface header ensure failed:", errMessage(err));
      } finally {
        inFlight.delete(channel);
        const again = requeued.get(channel);
        if (again) {
          requeued.delete(channel);
          ensure(client, channel, scopeId, kind, again);
        }
      }
    })();
  };
}

export async function onBotJoinedChannel(opts: {
  client: {
    chat: { postMessage: (args: SlackReplyArgs) => Promise<unknown> };
    conversations: {
      info: (args: { channel: string }) => Promise<{ channel?: ChannelMeta }>;
    };
  };
  channel: string | undefined;
  joinerUserId: string | undefined;
  botUserId: string;
  webUiPublicUrl: string | undefined;
  syncDirectory: () => Promise<void>;
  ensureHeader?: (channel: string) => void;
}): Promise<void> {
  const { client, channel, joinerUserId, botUserId, webUiPublicUrl, syncDirectory, ensureHeader } = opts;
  if (!channel || !joinerUserId || joinerUserId !== botUserId) return;
  const surfaceUrl = channelSurfaceUrl(webUiPublicUrl, channel);
  try {
    const info = (await client.conversations.info({ channel })).channel;
    if (!isExternallyShared(info)) {
      await client.chat.postMessage(
        slackReplyArgs(channel, channelWelcomeMessage(surfaceUrl), undefined, { unfurlLinks: false }),
      );
      ensureHeader?.(channel);
    }
  } catch {
    void 0;
  }
  try {
    await syncDirectory();
  } catch {
    void 0;
  }
}

export function encodeDeliveryTarget(channel: string, threadTs?: string): string {
  return threadTs ? `${channel}:${threadTs}` : channel;
}

async function slackUserIdFor(client: any, principalId: string): Promise<string> {
  if (!principalId.includes("@")) return principalId;
  const res = (await client.users.lookupByEmail({ email: principalId })) as { user?: { id?: string } };
  const id = res?.user?.id;
  if (!id) throw new Error(`no Slack member found for ${principalId}`);
  return id;
}

export async function openConversationFor(client: any, principalIds: readonly string[]): Promise<string> {
  const users: string[] = [];
  for (const p of principalIds) users.push(await slackUserIdFor(client, p));
  const opened = (await client.conversations.open({ users: users.join(",") })) as { channel?: { id?: string } };
  const channel = opened?.channel?.id;
  if (!channel) throw new Error("conversations.open returned no channel");
  return channel;
}

export function parseDeliveryTarget(target: string): { channel: string; threadTs?: string } {
  const i = target.indexOf(":");
  if (i < 0) return { channel: target };
  return { channel: target.slice(0, i), threadTs: target.slice(i + 1) };
}

export function deliveryCandidatesFor(
  kind: "dm" | "channel" | "group",
  channel: string,
  replyThreadTs: string | undefined,
  channelName: string | undefined,
): { target: string; label: string }[] | undefined {
  if (kind === "dm") return undefined;
  let wholeLabel = "the whole channel";
  if (kind === "group") wholeLabel = "the group DM";
  else if (channelName) wholeLabel = `#${channelName} (the whole channel)`;
  return [
    { target: encodeDeliveryTarget(channel, replyThreadTs), label: "this thread" },
    { target: encodeDeliveryTarget(channel), label: wholeLabel },
  ];
}

const DELIVERY_MAX_ATTEMPTS = 5;
const DELIVERY_MAX_TRACKED = 1000;
const DELIVERY_GIVEUP_RETRY_MS = 5 * 60_000;

export interface DeliveryTracker {
  givenUp(id: string): boolean;
  posted(id: string): { ackBody?: unknown } | undefined;
  markPosted(id: string, ackBody?: unknown): void;
  recordFailure(id: string): boolean;
  clear(id: string): void;
}

function capMap<K, V>(map: Map<K, V>, max: number): void {
  while (map.size > max) {
    const oldest = map.keys().next().value;
    if (oldest === undefined) return;
    map.delete(oldest);
  }
}

export function createDeliveryTracker(
  opts: { maxAttempts?: number; maxTracked?: number; giveUpRetryMs?: number } = {},
): DeliveryTracker {
  const maxAttempts = opts.maxAttempts ?? DELIVERY_MAX_ATTEMPTS;
  const maxTracked = opts.maxTracked ?? DELIVERY_MAX_TRACKED;
  const giveUpRetryMs = opts.giveUpRetryMs ?? DELIVERY_GIVEUP_RETRY_MS;
  const failures = new Map<string, number>();
  const posted = new Map<string, { ackBody?: unknown }>();

  const dead = new Map<string, number>();
  return {
    givenUp(id) {
      const until = dead.get(id);
      if (until === undefined) return false;
      if (Date.now() < until) return true;
      dead.delete(id);
      console.error(`[slack-plugin] delivery ${id} give-up window expired — retrying delivery`);
      return false;
    },
    posted(id) {
      return posted.get(id);
    },
    markPosted(id, ackBody) {
      posted.set(id, ackBody === undefined ? {} : { ackBody });
      while (posted.size > maxTracked) {
        const oldest = posted.keys().next().value;
        if (oldest === undefined) break;
        posted.delete(oldest);
        failures.delete(oldest);
        dead.set(oldest, Date.now() + giveUpRetryMs);
        capMap(dead, maxTracked);
      }
    },
    recordFailure(id) {
      const count = (failures.get(id) ?? 0) + 1;
      if (count >= maxAttempts) {
        failures.delete(id);
        posted.delete(id);
        dead.set(id, Date.now() + giveUpRetryMs);
        capMap(dead, maxTracked);
        return true;
      }
      failures.set(id, count);
      capMap(failures, maxTracked);
      return false;
    },
    clear(id) {
      failures.delete(id);
      posted.delete(id);
      dead.delete(id);
    },
  };
}

export async function deliverWithRetry(opts: {
  tracker: DeliveryTracker;
  id: string;
  post(): Promise<unknown>;
  ack(body?: unknown): Promise<void>;
  onError(stage: "post" | "ack", err: unknown, gaveUp: boolean): void;
}): Promise<void> {
  const { tracker, id } = opts;
  if (tracker.givenUp(id)) return;
  let postedState = tracker.posted(id);
  if (!postedState) {
    try {
      const ackBody = await opts.post();
      tracker.markPosted(id, ackBody ?? undefined);
      postedState = tracker.posted(id);
    } catch (err) {
      opts.onError("post", err, tracker.recordFailure(id));
      return;
    }
  }
  try {
    await opts.ack(postedState?.ackBody);
    tracker.clear(id);
  } catch (err) {
    opts.onError("ack", err, tracker.recordFailure(id));
  }
}

export interface PostMessageArgs {
  channel: string;
  text?: string;
  thread_ts?: string;
  metadata?: DeliveryMetadata;
  [key: string]: unknown;
}

export interface DeliveryMetadata {
  event_type: string;
  event_payload: Record<string, unknown>;
}

export function deliveryMetadata(idempotencyKey: string): DeliveryMetadata {
  return { event_type: "qm_delivery", event_payload: { idempotency_key: idempotencyKey } };
}
export interface PostVerifyClient {
  chat: { postMessage(args: PostMessageArgs): Promise<unknown> };
  conversations: {
    history(args: {
      channel: string;
      limit: number;
      include_all_metadata: boolean;
      oldest: string;
      inclusive: boolean;
      cursor?: string;
    }): Promise<unknown>;
    replies(args: {
      channel: string;
      ts: string;
      limit: number;
      include_all_metadata: boolean;
      oldest: string;
      inclusive: boolean;
      cursor?: string;
    }): Promise<unknown>;
  };
}

export async function findPostedByKey(
  client: PostVerifyClient,
  args: PostMessageArgs,
  idempotencyKey: string,
  oldest: string,
): Promise<{ ts: string; channel: string } | undefined> {
  const channel = args.channel;
  let cursor: string | undefined;
  do {
    const paging = {
      channel,
      limit: 100,
      include_all_metadata: true,
      oldest,
      inclusive: true,
      ...(cursor ? { cursor } : {}),
    };
    const scan = args.thread_ts
      ? await client.conversations.replies({ ...paging, ts: args.thread_ts })
      : await client.conversations.history(paging);
    const page = scan as {
      messages?: Array<{
        ts?: string;
        metadata?: { event_type?: string; event_payload?: { idempotency_key?: string } };
      }>;
      response_metadata?: { next_cursor?: string };
    };
    const hit = (page.messages ?? []).find(
      (m) => m.metadata?.event_type === "qm_delivery" && m.metadata.event_payload?.idempotency_key === idempotencyKey,
    );
    if (hit?.ts) return { ts: String(hit.ts), channel };
    cursor = page.response_metadata?.next_cursor?.trim() || undefined;
  } while (cursor);
  return undefined;
}

export function statusPlaceholderKey(runId: string): string {
  return `status:run:${runId}`;
}

export function recoveryVerifyOldest(createdAt: number | undefined, editRef: string | undefined): string | undefined {
  const bounds: number[] = [];
  if (typeof createdAt === "number") bounds.push(createdAt / 1000 - 60);
  const editRefSec = Number(editRef);
  if (editRef && Number.isFinite(editRefSec)) bounds.push(editRefSec - 5);
  return bounds.length ? String(Math.min(...bounds)) : undefined;
}

export const SLACK_TEXT_LIMIT = 40000;

export const SLACK_POST_SPLIT_LIMIT = 3_800;

export interface PostedPart {
  ts: string | undefined;
  channel: string;
  reused?: boolean;
  text: string;
}

function splitPostKey(idempotencyKey: string, partIndex: number): string {
  return partIndex === 0 ? idempotencyKey : `${idempotencyKey}#p${partIndex + 1}`;
}

export async function postWithVerify(
  client: PostVerifyClient,
  args: PostMessageArgs,
  idempotencyKey: string,
  opts?: { attempts?: number; verifyFirst?: boolean; verifyOldest?: string; verifyBestEffort?: boolean },
): Promise<{ ts: string | undefined; channel: string; reused?: boolean; parts?: PostedPart[] }> {
  const fullText = typeof args.text === "string" ? args.text : "";
  const batches: PostMessageArgs[] = [];
  if (Array.isArray(args.blocks) && args.blocks.length > 50) {
    for (let offset = 0; offset < args.blocks.length; offset += 50) {
      const blocks = args.blocks.slice(offset, offset + 50);
      const text = blocks
        .filter((block) => block.type === "section" && typeof block.text?.text === "string")
        .map((block) => block.text.text)
        .join("\n");
      batches.push({ ...args, blocks, text });
    }
  } else if (!args.blocks && fullText.length > SLACK_POST_SPLIT_LIMIT) {
    batches.push(...safeChunks(fullText, SLACK_POST_SPLIT_LIMIT).map((text) => ({ ...args, text })));
  }
  if (batches.length) {
    const parts: PostedPart[] = [];
    for (const [i, batch] of batches.entries()) {
      const text = batch.text ?? "";
      const res = await postWithVerify(client, batch, splitPostKey(idempotencyKey, i), {
        ...opts,
        verifyFirst: true,
        verifyBestEffort: !opts?.verifyFirst,
      });
      parts.push({
        ts: res.ts,
        channel: res.channel,
        ...(res.reused !== undefined ? { reused: res.reused } : {}),
        text,
      });
    }
    const first = parts[0]!;
    return {
      ts: first.ts,
      channel: first.channel,
      ...(parts.every((p) => p.reused) ? { reused: true } : {}),
      parts,
    };
  }
  if (args.blocks && fullText.length > SLACK_TEXT_LIMIT - 1_000) {
    args.text = safeClip(fullText, SLACK_TEXT_LIMIT - 1_000);
  }
  const maxAttempts = opts?.attempts ?? 3;
  const verifyOldest = opts?.verifyOldest ?? String((Date.now() - 5_000) / 1000);
  args.metadata = deliveryMetadata(idempotencyKey);
  if (opts?.verifyFirst) {
    const found = opts.verifyBestEffort
      ? await findPostedByKey(client, args, idempotencyKey, verifyOldest).catch(swallowAs("slack: part verify", null))
      : await findPostedByKey(client, args, idempotencyKey, verifyOldest);
    if (found) return { ...found, reused: true };
  }
  let lastErr: unknown;
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const res = (await client.chat.postMessage(args)) as { ts?: string; channel?: string };
      return { ts: res.ts === undefined ? undefined : String(res.ts), channel: String(res.channel ?? args.channel) };
    } catch (err) {
      lastErr = err;
      const code = (err as { code?: string }).code;
      if (code === "slack_webapi_platform_error") throw err;
      if (code === "slack_webapi_rate_limited_error") {
        const retryAfter = (err as { retryAfter?: number }).retryAfter ?? 1;
        await sleep(retryAfter * 1000);

        try {
          const found = await findPostedByKey(client, args, idempotencyKey, verifyOldest);
          if (found) return { ...found, reused: true };
        } catch {
          /* verification is best-effort on this path */
        }
        continue;
      }
      let found: { ts: string; channel: string } | undefined;
      try {
        found = await findPostedByKey(client, args, idempotencyKey, verifyOldest);
      } catch {
        throw err;
      }
      if (found) return found;
    }
  }
  throw lastErr;
}