Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

21.1 KB
Raw Blame
/**
 * The OpenTag pairing: OpenBot's Slack and Microsoft Teams reachability.
 *
 * OpenTag (CopilotKit's open-source Slack/Teams front on the Channels SDK) calls one AG-UI agent at
 * `AGENT_URL` with `Authorization: AGENT_AUTH_HEADER`. OpenBot is that agent: the shared secret is
 * checked in constant time, OpenTag's structured sender context names the Slack/Teams person, and the
 * person's authenticated delivery binding decides which owner, Bot and canonical thread the turn runs
 * in. Nothing in the message text or the RunAgentInput can choose an owner.
 *
 * Human-in-the-loop follows OpenTag's `confirm_write` contract (`app/interrupt.ts`,
 * `app/human-in-the-loop/confirm-write.tsx`): a CUSTOM `on_interrupt` event whose value carries
 * `__opentag_interrupt_id__` (32 lowercase hex) and `__copilotkit_interrupt_value__`
 * `{ action: "confirm_write", args }`. A card click re-runs the agent with
 * `forwardedProps.command.resume = { [interruptId]: { confirmed, always?, by } }`. The interrupt id is
 * the OpenBot approval id without dashes, and the decision still goes through the approvals service.
 *
 * Proactive messages (no Slack turn open) go the other way: OpenBot POSTs to OpenTag's
 * `/openbot/deliver`, because a managed Channel can only post inside a live delivery.
 */
import { timingSafeEqual } from "node:crypto";
import { z } from "zod";
import { DELIVERY_REQUEST_TIMEOUT_MS } from "../timeouts";
import {
  type BindingTransport,
  type ChatTransport,
  DeliveryProviderError,
  type DeliverySender,
  type ProviderFetch,
  providerJson,
} from "./types";

export type OpenTagConfig = {
  /** Shared both ways: OpenTag sends `Bearer <secret>`, and OpenBot sends it back on deliveries. */
  secret: string;
  /** OpenTag's base URL for proactive delivery; absent means proactive Slack/Teams sends fail visibly. */
  url?: string;
  /** Optional `{seed}`/`{agentId}` template for a public PNG avatar Slack can show as the Bot's icon. */
  iconUrlTemplate?: string;
  fetch?: ProviderFetch;
};

export const OPENTAG_SENDER_CONTEXT = "openbot.sender";

function sameSecret(expected: string, presented: string) {
  const a = Buffer.from(expected);
  const b = Buffer.from(presented);
  // Compare equal-length buffers so the check leaks neither content nor, via an early exit, length.
  const padded = Buffer.alloc(a.length);
  b.copy(padded);
  return timingSafeEqual(a, padded) && a.length === b.length;
}

export function createOpenTagTransport(config: OpenTagConfig) {
  const wire = config.fetch ?? fetch;
  const bearer = `Bearer ${config.secret}`;
  function iconUrl(sender?: DeliverySender) {
    if (!sender || !config.iconUrlTemplate) return undefined;
    return config.iconUrlTemplate
      .replaceAll(
        "{seed}",
        encodeURIComponent(sender.avatarSeed ?? sender.name),
      )
      .replaceAll("{agentId}", encodeURIComponent(sender.agentId));
  }
  return {
    config,
    /** Constant-time check of the `Authorization` header OpenTag presents. */
    authenticates(header: string | undefined | null) {
      return typeof header === "string" && sameSecret(bearer, header.trim());
    },
    /**
     * Whether a Slack user is in a channel, answered by OpenTag with the workspace's bot token
     * (`POST /openbot/membership`). Fails closed: any error or missing configuration is `false`.
     * Installed for Slack triggers with `useSlackChannelMembership`.
     */
    async isMember(input: {
      teamId: string;
      slackUserId: string;
      channelId: string;
    }): Promise<boolean> {
      if (!config.url) return false;
      try {
        const response = await wire(
          new URL("/openbot/membership", config.url),
          {
            method: "POST",
            signal: AbortSignal.timeout(15_000),
            headers: {
              authorization: bearer,
              "content-type": "application/json",
            },
            body: JSON.stringify(input),
          },
        );
        if (!response.ok) return false;
        const body = (await response.json()) as { member?: unknown };
        return body.member === true;
      } catch {
        return false;
      }
    },
    async send(input: {
      id: string;
      address: string;
      text: string;
      transport?: BindingTransport;
      sender?: DeliverySender;
    }) {
      if (!config.url)
        throw new DeliveryProviderError(
          "OpenTag",
          "proactive_delivery_not_configured",
        );
      const platform: ChatTransport =
        input.transport === "teams" ? "teams" : "slack";
      let response: Response;
      try {
        response = await wire(new URL("/openbot/deliver", config.url), {
          method: "POST",
          signal: AbortSignal.timeout(DELIVERY_REQUEST_TIMEOUT_MS),
          headers: {
            authorization: bearer,
            "content-type": "application/json",
          },
          body: JSON.stringify({
            id: input.id,
            platform,
            address: input.address,
            text: input.text,
            ...(input.sender
              ? {
                  sender: {
                    name: input.sender.name,
                    ...(iconUrl(input.sender)
                      ? { iconUrl: iconUrl(input.sender) }
                      : {}),
                  },
                }
              : {}),
          }),
        });
      } catch {
        throw new DeliveryProviderError("OpenTag", "network_error", true);
      }
      if (!response.ok) {
        let code = `HTTP_${response.status}`;
        try {
          const body = (await response.json()) as { error?: unknown };
          if (
            typeof body.error === "string" &&
            /^[a-z0-9_]{1,64}$/.test(body.error)
          )
            code = body.error;
        } catch {}
        throw new DeliveryProviderError(
          "OpenTag",
          code,
          response.status >= 500,
        );
      }
      const body = await providerJson("OpenTag", response);
      if (body.ok !== true || typeof body.id !== "string")
        throw new DeliveryProviderError("OpenTag", "missing_message_id", true);
      // Recorded as `<conversation>/<ts>` so a "sent" row names where it landed and can be checked
      // against the conversation's history.
      return {
        id:
          typeof body.channel === "string"
            ? `${body.channel}/${body.id}`
            : body.id,
        status: "sent" as const,
      };
    },
  };
}
export type OpenTagTransport = ReturnType<typeof createOpenTagTransport>;

/** The part of `RunAgentInput` this endpoint reads. Unknown keys (tools, state) pass untouched. */
const runInputSchema = z.object({
  threadId: z.string().min(1).max(512),
  runId: z.string().min(1).max(512),
  messages: z
    .array(
      z
        .object({
          id: z.string().optional(),
          role: z.string(),
          content: z.unknown().optional(),
        })
        .passthrough(),
    )
    .max(2000)
    .default([]),
  context: z
    .array(z.object({ description: z.string(), value: z.string() }))
    .max(200)
    .default([]),
  forwardedProps: z.unknown().optional(),
  tools: z
    .array(z.object({ name: z.string() }).passthrough())
    .max(500)
    .default([]),
});
export type OpenTagRunInput = z.infer<typeof runInputSchema>;
export const parseOpenTagRunInput = (value: unknown) =>
  runInputSchema.parse(value);

/**
 * OpenTag's managed-Channel user id, `provider:tenant:actor`. The actor half is taken as the rest of
 * the string because Teams user ids (`29:…`) contain colons of their own.
 */
export function parseChannelUser(
  value: unknown,
): { transport: ChatTransport; realm: string; identity: string } | null {
  if (typeof value !== "string" || value.length > 512) return null;
  const first = value.indexOf(":");
  const second = value.indexOf(":", first + 1);
  if (first < 1 || second < first + 2 || second === value.length - 1)
    return null;
  const provider = value.slice(0, first);
  if (provider !== "slack" && provider !== "teams") return null;
  return {
    transport: provider,
    realm: value.slice(first + 1, second),
    identity: value.slice(second + 1),
  };
}

/** Conversation kinds only the person and the app can read: a Slack DM, a Teams personal chat. */
const PRIVATE_KINDS = new Set([
  "im",
  "dm",
  "direct",
  "direct_message",
  "personal",
]);

/** The sender OpenTag vouches for. Exactly one structured entry, or nobody. */
export function senderFromContext(input: OpenTagRunInput) {
  const entries = input.context.filter(
    (entry) => entry.description === OPENTAG_SENDER_CONTEXT,
  );
  if (entries.length !== 1) return null;
  let value: {
    user?: unknown;
    event?: unknown;
    conversation?: unknown;
    mentioned?: unknown;
    observe?: unknown;
    reaction?: unknown;
  };
  try {
    value = JSON.parse(entries[0]?.value ?? "");
  } catch {
    return null;
  }
  const person = parseChannelUser(value?.user);
  if (!person) return null;
  const conversation =
    value.conversation && typeof value.conversation === "object"
      ? (value.conversation as { id?: unknown; kind?: unknown })
      : {};
  const kind = typeof conversation.kind === "string" ? conversation.kind : "";
  const id = typeof conversation.id === "string" ? conversation.id : "";
  return {
    ...person,
    conversationId: id || undefined,
    mentioned: value.mentioned === true,
    /** Not a request: an event responsibilities may watch for. No turn runs for it. */
    observe:
      value.observe === "message" || value.observe === "reaction_added"
        ? (value.observe as "message" | "reaction_added")
        : undefined,
    reaction:
      typeof value.reaction === "string" && value.reaction.length <= 100
        ? value.reaction.replaceAll(":", "")
        : undefined,
    event:
      typeof value.event === "string" && value.event.length <= 512
        ? value.event
        : undefined,
    /**
     * Whether only this person can read what is posted back. Unknown counts as shared, so an answer
     * drawn from the owner's private conversation never lands where others can read it by default.
     */
    private:
      PRIVATE_KINDS.has(kind.toLowerCase()) ||
      (person.transport === "slack" && /^D[A-Z0-9]{8,}$/.test(id)),
  };
}

/** The newest person message, as plain text, with Slack's own `<@U…>` mention tokens removed. */
export function latestUserMessage(input: OpenTagRunInput) {
  for (let index = input.messages.length - 1; index >= 0; index -= 1) {
    const message = input.messages[index];
    if (message?.role !== "user") continue;
    const text =
      typeof message.content === "string"
        ? message.content
        : Array.isArray(message.content)
          ? message.content
              .map((part) =>
                part &&
                typeof part === "object" &&
                "type" in part &&
                part.type === "text" &&
                "text" in part &&
                typeof part.text === "string"
                  ? part.text
                  : "",
              )
              .join("\n")
          : "";
    return {
      id: message.id,
      text: text.replace(/<@[A-Z0-9]+(?:\|[^>]*)?>/g, "").trim(),
    };
  }
  return null;
}

const resumeSchema = z.object({
  confirmed: z.boolean(),
  always: z.boolean().optional(),
  by: z.string().max(512).optional(),
});
/** A card click answering one OpenBot approval, or null when this run is not a resume. */
export function resumeFromInput(input: OpenTagRunInput) {
  const props = input.forwardedProps;
  if (!props || typeof props !== "object" || !("command" in props)) return null;
  const command = (props as { command?: unknown }).command;
  if (!command || typeof command !== "object" || !("resume" in command))
    return null;
  const resume = (command as { resume?: unknown }).resume;
  if (!resume || typeof resume !== "object") return { invalid: true as const };
  const entries = Object.entries(resume);
  if (entries.length !== 1) return { invalid: true as const };
  const [interruptId, value] = entries[0] ?? [];
  const parsed = resumeSchema.safeParse(value);
  if (!interruptId || !/^[0-9a-f]{32}$/.test(interruptId) || !parsed.success)
    return { invalid: true as const };
  return {
    invalid: false as const,
    approvalId: approvalIdFromInterrupt(interruptId),
    ...parsed.data,
  };
}

export const interruptIdForApproval = (approvalId: string) =>
  approvalId.replaceAll("-", "").toLowerCase();
export const approvalIdFromInterrupt = (interruptId: string) =>
  `${interruptId.slice(0, 8)}-${interruptId.slice(8, 12)}-${interruptId.slice(12, 16)}-${interruptId.slice(16, 20)}-${interruptId.slice(20)}`;

export function confirmWriteInterrupt(input: {
  approvalId: string;
  action: string;
  approver: string;
  effect?: string;
  fields: { label: string; value: string }[];
}) {
  return {
    __opentag_interrupt_id__: interruptIdForApproval(input.approvalId),
    __copilotkit_interrupt_value__: {
      action: "confirm_write",
      args: {
        action: input.action,
        fields: input.fields,
        approver: input.approver,
        ...(input.effect &&
        ["read", "write", "destructive"].includes(input.effect)
          ? { effect: input.effect }
          : {}),
        allow_always: true,
      },
    },
  };
}

/** Approver-readable rows from an already-redacted approval preview. */
export function approvalFields(preview: unknown) {
  if (!preview || typeof preview !== "object" || Array.isArray(preview))
    return preview === undefined
      ? []
      : [{ label: "Arguments", value: clip(JSON.stringify(preview)) }];
  return Object.entries(preview)
    .slice(0, 10)
    .map(([label, value]) => ({
      label: clip(label, 60),
      value: clip(typeof value === "string" ? value : JSON.stringify(value)),
    }));
}
function clip(value: string | undefined, max = 300) {
  const text = value ?? "";
  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
}

/** Minimal AG-UI SSE writer: `data: <event>\n\n` per event, as `@ag-ui/client`'s parser reads it. */
/** How often a quiet OpenTag stream says it is still working. See {@link agUiStream}. */
export const AG_UI_HEARTBEAT_MS = 5_000;
/** `Bun.serve`'s default idle timeout, which the heartbeat has to beat. */
export const BUN_IDLE_TIMEOUT_MS = 10_000;

export function agUiStream(
  run: (emit: (event: Record<string, unknown>) => void) => Promise<void>,
  /*
   * Under Bun's own idle limit. `Bun.serve` closes a connection that has sent nothing for 10
   * seconds, and at 20 a turn longer than that lost its stream: OpenTag read the headers and
   * RUN_STARTED, the socket closed under it, and the Slack message went unanswered.
   */
  heartbeatMs = AG_UI_HEARTBEAT_MS,
) {
  const encoder = new TextEncoder();
  return new ReadableStream<Uint8Array>({
    async start(controller) {
      let closed = false;
      const emit = (event: Record<string, unknown>) => {
        if (!closed)
          controller.enqueue(
            encoder.encode(`data: ${JSON.stringify(event)}\n\n`),
          );
      };
      // A long governed turn says nothing for minutes; an ignored CUSTOM event keeps proxies and the
      // runner's socket from treating the silence as a dead stream.
      const heartbeat = setInterval(
        () => emit({ type: "CUSTOM", name: "openbot.working", value: {} }),
        heartbeatMs,
      );
      heartbeat.unref?.();
      try {
        await run(emit);
      } finally {
        clearInterval(heartbeat);
        closed = true;
        controller.close();
      }
    },
  });
}

export function textEvents(messageId: string, text: string) {
  if (!text) return [];
  return [
    { type: "TEXT_MESSAGE_START", messageId, role: "assistant" },
    { type: "TEXT_MESSAGE_CONTENT", messageId, delta: text },
    { type: "TEXT_MESSAGE_END", messageId },
  ];
}

/** OpenTag's chart component (`app/tools/render-chart.tsx`): native in Slack and Teams. */
export const OPENTAG_CHART_TOOL = "render_chart";
/** Our component calls carry this id prefix, so the Channel's follow-up run is recognised. */
export const COMPONENT_CALL_PREFIX = "openbot-component-";

const LABEL_MAX = 20;
/** Labels clipped to OpenTag's limit and kept unique, since categories must be. */
function labelsFor(raw: string[]): string[] {
  const seen = new Set<string>();
  return raw.map((label, index) => {
    let clipped = clip(label.trim() || `Item ${index + 1}`, LABEL_MAX);
    for (let n = 2; seen.has(clipped); n++)
      clipped = `${clip(label, LABEL_MAX - String(n).length - 1)} ${n}`;
    seen.add(clipped);
    return clipped;
  });
}

type Point = { label: string; value: number };
const isPoint = (value: unknown): value is Point =>
  !!value &&
  typeof value === "object" &&
  typeof (value as Point).label === "string" &&
  Number.isFinite((value as Point).value);

/**
 * One of OpenBot's gallery charts as OpenTag's `render_chart` arguments, or null when it is not a
 * chart or cannot be drawn within that component's limits (the reply text still carries it).
 */
export function chartForOpenTag(component: {
  name: string;
  args: Record<string, unknown>;
}): Record<string, unknown> | null {
  const { args } = component;
  const title = clip(
    typeof args.title === "string" && args.title.trim()
      ? args.title.trim()
      : "Chart",
    50,
  );
  if (component.name === "showBarChart" || component.name === "showPieChart") {
    const points = (Array.isArray(args.points) ? args.points : [])
      .filter(isPoint)
      .slice(0, component.name === "showPieChart" ? 12 : 20);
    if (points.length === 0) return null;
    const labels = labelsFor(points.map(({ label }) => label));
    if (component.name === "showPieChart") {
      const segments = points
        .map(({ value }, index) => ({ label: labels[index], value }))
        .filter(({ value }) => value > 0);
      return segments.length
        ? { title, chart: { type: "pie", segments } }
        : null;
    }
    return {
      title,
      chart: {
        type: "bar",
        series: [
          {
            name: clip(title, LABEL_MAX),
            data: points.map(({ value }, index) => ({
              label: labels[index],
              value,
            })),
          },
        ],
        axis_config: { categories: labels },
      },
    };
  }
  if (
    component.name === "showLineChart" ||
    component.name === "showAreaChart"
  ) {
    const rawLabels = (Array.isArray(args.labels) ? args.labels : [])
      .filter((label): label is string => typeof label === "string")
      .slice(0, 20);
    if (rawLabels.length === 0) return null;
    const labels = labelsFor(rawLabels);
    const series = (Array.isArray(args.series) ? args.series : [])
      .filter(
        (entry): entry is { name: string; values: number[] } =>
          !!entry &&
          typeof entry === "object" &&
          typeof entry.name === "string" &&
          Array.isArray(entry.values),
      )
      .slice(0, 12);
    if (series.length === 0) return null;
    const names = labelsFor(series.map(({ name }) => name));
    return {
      title,
      chart: {
        type: component.name === "showAreaChart" ? "area" : "line",
        series: series.map(({ values }, index) => ({
          name: names[index],
          data: labels.map((label, at) => ({
            label,
            value: Number.isFinite(values[at]) ? Number(values[at]) : 0,
          })),
        })),
        axis_config: { categories: labels },
      },
    };
  }
  return null;
}

/**
 * The line said under a chart drawn natively, saying where its figures came from, or "" when the
 * Bot said nothing about that. OpenTag's chart has no caption, so without it a Slack or Teams chart
 * would lose what the same chart says in OpenBot. Mirrors `Sources` in the app's gallery charts.
 */
export function chartSourcesLine(args: Record<string, unknown>): string {
  const seen = new Set<string>();
  const named: string[] = [];
  for (const entry of Array.isArray(args.sources) ? args.sources : []) {
    const title = typeof entry?.title === "string" ? entry.title.trim() : "";
    if (!title) continue;
    const url =
      typeof entry.url === "string" && /^https?:\/\//i.test(entry.url)
        ? entry.url
        : undefined;
    const key = `${title}|${url ?? ""}`;
    if (seen.has(key)) continue;
    seen.add(key);
    named.push(url ? `[${title}](${url})` : title);
  }
  const asOf = typeof args.asOf === "string" ? args.asOf.trim() : "";
  return [
    args.basis === "own-knowledge"
      ? "From the Bot's own knowledge. Not checked against a source."
      : "",
    named.length ? `Sources: ${named.join(", ")}` : "",
    asOf ? `As of ${asOf}` : "",
  ]
    .filter(Boolean)
    .join(" · ");
}

/** A component call for the Channel to draw, as AG-UI tool-call events. */
export function componentCallEvents(
  toolCallId: string,
  toolCallName: string,
  args: Record<string, unknown>,
) {
  return [
    { type: "TOOL_CALL_START", toolCallId, toolCallName },
    { type: "TOOL_CALL_ARGS", toolCallId, delta: JSON.stringify(args) },
    { type: "TOOL_CALL_END", toolCallId },
  ];
}

/** Whether this run is only the Channel reporting that it drew our component: nothing to answer. */
export function isComponentFollowUp(input: OpenTagRunInput): boolean {
  const last = input.messages.at(-1) as
    | { role?: string; toolCallId?: unknown }
    | undefined;
  return (
    last?.role === "tool" &&
    typeof last.toolCallId === "string" &&
    last.toolCallId.startsWith(COMPONENT_CALL_PREFIX)
  );
}