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.

15.0 KB
Raw Blame
// `agent.event`: the part of each AG-UI event that CopilotKit's own agent events (`agent.run`, `agent.message`,
// `tool.call`) do not carry, so every piece of the agent's side lands in the Trajectory exactly once and never one event
// per streamed token. A text or reasoning message is CopilotKit's `agent.message` alone; a tool call's arguments are one
// `TOOL_CALL_ARGS` holding the whole string the library assembled, sent at TOOL_CALL_END; a tool result is the tool's
// `agent.message` (its text) beside a `TOOL_CALL_RESULT` that names the call it answers; consecutive STATE_DELTAs (and
// ACTIVITY_DELTAs of one activity) with nothing between them are one, their JSON Patch operations concatenated, which
// applies exactly as the parts did. History in a RUN_STARTED's `input` or a MESSAGES_SNAPSHOT keeps only what no event
// carried before: a message already carried is its id and role. A frontend tool's result, which the page puts into the
// history itself and CopilotKit announces nowhere, is carried there, in the next run's `input`, once. A RUN_STARTED's
// `tools` and `context` (the page's whole tool list and context, the same in every run of most pages) are carried when
// they differ from what the Thread's runs carried before.
import type { BaseEvent, Message } from "@ag-ui/client";

/** An AG-UI event as `agent.event` carries it. */
export type AgentEventPayload = { type: string; [field: string]: unknown };

/** What a Thread's events have already carried, so nothing is carried twice; shared by every tab's agent for the Thread.
 * A message maps to the text its `agent.message` carried (null when it carried none); a tool call to its name and the
 * arguments its `TOOL_CALL_ARGS` carried; `setup` to the JSON of the `tools` and of the `context` a RUN_STARTED of the
 * Thread carried last. */
export type Expressed = {
  messages: Map<string, string | null>;
  toolCalls: Map<string, { name: string; arguments: string | null }>;
  setup: Map<"tools" | "context", string>;
};

export const createExpressed = (): Expressed => ({
  messages: new Map(),
  toolCalls: new Map(),
  setup: new Map(),
});

/**
 * Per AG-UI event type: the fields CopilotKit's own events carry, the ids kept beside what remains so it can be joined to
 * them, and whether the event goes out always, only when something remains, or never (a streamed delta, carried
 * assembled). An unlisted type goes out whole.
 */
const POLICY: Record<
  string,
  { carried: string[]; keys: string[]; when: "always" | "rest" | "never" }
> = {
  RUN_STARTED: { carried: ["threadId", "runId"], keys: [], when: "rest" },
  RUN_FINISHED: { carried: ["threadId", "runId"], keys: [], when: "rest" },
  TEXT_MESSAGE_START: { carried: ["role"], keys: ["messageId"], when: "rest" },
  TEXT_MESSAGE_CONTENT: { carried: [], keys: [], when: "never" },
  TEXT_MESSAGE_END: { carried: [], keys: ["messageId"], when: "rest" },
  TOOL_CALL_START: {
    carried: ["toolCallName", "parentMessageId"],
    keys: ["toolCallId"],
    when: "rest",
  },
  TOOL_CALL_ARGS: { carried: [], keys: [], when: "never" },
  TOOL_CALL_END: { carried: [], keys: ["toolCallId"], when: "rest" },
  TOOL_CALL_RESULT: {
    carried: ["role"],
    keys: ["messageId", "toolCallId"],
    when: "always",
  },
  REASONING_START: { carried: [], keys: ["messageId"], when: "always" },
  REASONING_MESSAGE_START: {
    carried: ["role"],
    keys: ["messageId"],
    when: "rest",
  },
  REASONING_MESSAGE_CONTENT: { carried: [], keys: [], when: "never" },
  REASONING_MESSAGE_END: { carried: [], keys: ["messageId"], when: "rest" },
  REASONING_END: { carried: [], keys: ["messageId"], when: "always" },
};

/** Intelligence's own bookkeeping (its event id, sequence and ingest id): not the agent's. It rides in the `metadata` of
 * every event Intelligence relays, and in the `metadata` of each message the page got from it, so a run's history
 * (RUN_STARTED's `input.messages`, a MESSAGES_SNAPSHOT) carries it too. */
const INTELLIGENCE_METADATA = /^cpki_/;

const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value);

/** A `metadata` without Intelligence's bookkeeping; undefined when nothing of it remains. */
const ownMetadata = (
  metadata: Record<string, unknown>,
): Record<string, unknown> | undefined => {
  const kept = Object.fromEntries(
    Object.entries(metadata).filter(
      ([key]) => !INTELLIGENCE_METADATA.test(key),
    ),
  );
  return Object.keys(kept).length > 0 ? kept : undefined;
};

/** A value with Intelligence's bookkeeping taken out of every `metadata` in it, at any depth: a copy wherever something
 * was taken out, the value itself where nothing was. */
const withoutIntelligence = (value: unknown): unknown => {
  if (Array.isArray(value)) {
    const items = value.map(withoutIntelligence);
    return items.some((item, index) => item !== value[index]) ? items : value;
  }
  if (!isRecord(value)) return value;
  let out: Record<string, unknown> | null = null;
  for (const [key, item] of Object.entries(value)) {
    const kept =
      key === "metadata" && isRecord(item)
        ? ownMetadata(withoutIntelligence(item) as Record<string, unknown>)
        : withoutIntelligence(item);
    if (kept === item) continue;
    out ??= { ...value };
    if (kept === undefined) delete out[key];
    else out[key] = kept;
  }
  return out ?? value;
};

/** A field of an event that is not the agent's: its own clock (the Trajectory event has one) and Intelligence's
 * bookkeeping wherever it sits. Undefined when nothing of it remains. */
const withoutTransport = (
  field: string,
  value: unknown,
): unknown | undefined => {
  if (field === "timestamp") return undefined;
  if (field === "metadata" && isRecord(value))
    return ownMetadata(withoutIntelligence(value) as Record<string, unknown>);
  return withoutIntelligence(value);
};

type Pending = {
  kind: "state" | "activity";
  payload: AgentEventPayload & { delta?: unknown[]; patch?: unknown[] };
  at: number;
};

export function createAgentEventBuilder(expressed: Expressed) {
  const results = new Map<string, AgentEventPayload>();
  let pending: Pending | null = null;

  const textOf = (message: Message): string | null =>
    typeof message.content === "string" ? message.content : null;

  /** A message as history carries it: what an earlier event carried taken out, its id and role kept. Intelligence's
   * bookkeeping in its `metadata` is not the message's, so a message an agent.message already carried is not carried
   * again for it. */
  const reduceMessage = (
    message: Message,
  ): { message: Record<string, unknown>; carriedBefore: boolean } => {
    const out = {
      ...(withoutIntelligence(message) as Record<string, unknown>),
    };
    const known = expressed.messages.get(message.id);
    const text = textOf(message);
    if (
      out.content === undefined ||
      (text !== null && known !== undefined && known === text)
    )
      delete out.content;
    if (message.role === "assistant" && Array.isArray(message.toolCalls))
      out.toolCalls = message.toolCalls.map((call) => {
        const carried = expressed.toolCalls.get(call.id);
        return carried &&
          carried.name === call.function.name &&
          carried.arguments === call.function.arguments
          ? { id: call.id }
          : call;
      });
    const remaining = Object.keys(out).filter(
      (key) =>
        key !== "id" &&
        key !== "role" &&
        !(key === "toolCallId" && known !== undefined) &&
        !(
          key === "toolCalls" &&
          (out.toolCalls as Record<string, unknown>[]).every(
            (call) => Object.keys(call).length === 1,
          )
        ),
    );
    return { message: out, carriedBefore: remaining.length === 0 };
  };

  /** Everything a message carried in history is carried from now on. */
  const markCarried = (message: Message) => {
    if (!expressed.messages.has(message.id))
      expressed.messages.set(message.id, textOf(message));
    if (message.role === "assistant")
      for (const call of message.toolCalls ?? [])
        expressed.toolCalls.set(call.id, {
          name: call.function.name,
          arguments: call.function.arguments,
        });
  };

  /** A RUN_STARTED's `input` without its ids (they are the run's), with its `tools` and `context` only when they changed
   * from what the Thread's runs carried, and with only the history no event carried. */
  const reduceInput = (input: unknown): unknown => {
    if (!isRecord(input)) return input;
    const { threadId: _thread, runId: _run, messages, ...rest } = input;
    for (const field of ["tools", "context"] as const) {
      if (rest[field] === undefined) continue;
      const json = JSON.stringify(rest[field]);
      if (expressed.setup.get(field) === json) delete rest[field];
      else expressed.setup.set(field, json);
    }
    if (!Array.isArray(messages)) return rest;
    const fresh = (messages as Message[])
      .map((message) => ({ original: message, ...reduceMessage(message) }))
      .filter(({ carriedBefore }) => !carriedBefore);
    for (const { original } of fresh) markCarried(original);
    return fresh.length > 0
      ? { ...rest, messages: fresh.map(({ message }) => message) }
      : rest;
  };

  /** The event less what CopilotKit's events carry; null when that leaves nothing the policy sends. */
  const rest = (event: BaseEvent): AgentEventPayload | null => {
    const policy = POLICY[event.type] ?? {
      carried: [],
      keys: [],
      when: "always",
    };
    if (policy.when === "never") return null;
    const source = event as unknown as Record<string, unknown>;
    const kept: Record<string, unknown> = {};
    for (const key of policy.keys)
      if (source[key] !== undefined) kept[key] = source[key];
    const remaining: Record<string, unknown> = {};
    for (const [field, value] of Object.entries(source)) {
      if (
        field === "type" ||
        policy.carried.includes(field) ||
        policy.keys.includes(field)
      )
        continue;
      let left = withoutTransport(field, value);
      if (event.type === "RUN_STARTED" && field === "input")
        left = reduceInput(left);
      if (event.type === "TOOL_CALL_RESULT" && field === "content") {
        // A string result is the tool's agent.message text.
        if (typeof value === "string") continue;
      }
      if (event.type === "MESSAGES_SNAPSHOT" && field === "messages") {
        const messages = value as Message[];
        left = messages.map((message) => reduceMessage(message).message);
        for (const message of messages) markCarried(message);
      }
      // A copy: the library goes on to apply the event, and a patch's values become part of the state it then patches.
      if (left !== undefined) remaining[field] = structuredClone(left);
    }
    if (policy.when === "rest" && Object.keys(remaining).length === 0)
      return null;
    return { type: event.type, ...kept, ...remaining };
  };

  /** A delta merges into the one before it when it carries nothing but its operations. */
  const mergeable = (event: BaseEvent, operations: string): boolean => {
    const payload = rest(event);
    return (
      payload !== null &&
      Array.isArray(payload[operations]) &&
      Object.keys(payload).every((key) =>
        ["type", operations, "messageId", "activityType"].includes(key),
      )
    );
  };

  const continues = (held: Pending, event: BaseEvent): boolean => {
    const source = event as unknown as Record<string, unknown>;
    if (held.kind === "state")
      return event.type === "STATE_DELTA" && mergeable(event, "delta");
    return (
      event.type === "ACTIVITY_DELTA" &&
      source.messageId === held.payload.messageId &&
      source.activityType === held.payload.activityType &&
      mergeable(event, "patch")
    );
  };

  /** Holds a delta to merge with the next, or returns it to send now when it carries more than its operations. */
  const hold = (
    event: BaseEvent,
    kind: Pending["kind"],
    operations: "delta" | "patch",
    at: number,
  ): AgentEventPayload | null => {
    const payload = rest(event);
    if (payload === null) return null;
    if (!mergeable(event, operations)) return payload;
    if (pending !== null && pending.kind === kind) {
      (pending.payload[operations] as unknown[]).push(
        ...(payload[operations] as unknown[]),
      );
      pending.at = at;
    } else
      pending = {
        kind,
        payload: {
          ...payload,
          [operations]: [...(payload[operations] as unknown[])],
        },
        at,
      };
    return null;
  };

  return {
    rest,
    /** Before an event is applied: a held delta it does not continue goes out first. */
    flushBefore(
      event: BaseEvent,
    ): { payload: AgentEventPayload; at: number }[] {
      if (pending === null || continues(pending, event)) return [];
      const out = pending;
      pending = null;
      return [out];
    },
    /** The run is over: whatever is held goes out. */
    flushAll(): { payload: AgentEventPayload; at: number }[] {
      const out = pending;
      pending = null;
      return out === null ? [] : [out];
    },
    stateDelta: (event: BaseEvent, at: number) =>
      hold(event, "state", "delta", at),
    activityDelta: (event: BaseEvent, at: number) =>
      hold(event, "activity", "patch", at),
    toolCallStarted(
      event: BaseEvent & { toolCallId: string; toolCallName: string },
    ) {
      expressed.toolCalls.set(event.toolCallId, {
        name: event.toolCallName,
        arguments: null,
      });
    },
    /** TOOL_CALL_END: the arguments the library assembled for the call, as one TOOL_CALL_ARGS, then what is left of END. */
    toolCallEnded(
      event: BaseEvent & { toolCallId: string },
      messages: readonly Readonly<Message>[],
    ): AgentEventPayload[] {
      const out: AgentEventPayload[] = [];
      for (const message of messages) {
        if (message.role !== "assistant") continue;
        const call = message.toolCalls?.find(
          ({ id }) => id === event.toolCallId,
        );
        if (!call) continue;
        const carried = expressed.toolCalls.get(call.id);
        expressed.toolCalls.set(call.id, {
          name: carried?.name ?? call.function.name,
          arguments: call.function.arguments,
        });
        if (call.function.arguments !== "")
          out.push({
            type: "TOOL_CALL_ARGS",
            toolCallId: call.id,
            delta: call.function.arguments,
          });
        break;
      }
      const end = rest(event);
      if (end !== null) out.push(end);
      return out;
    },
    /** TOOL_CALL_RESULT goes out after the tool's agent.message, which the library announces once it holds the result. */
    toolCallResult(event: BaseEvent & { messageId: string }) {
      const payload = rest(event);
      if (payload !== null) results.set(event.messageId, payload);
    },
    afterMessage(message: Message): AgentEventPayload | null {
      const payload = results.get(message.id) ?? null;
      results.delete(message.id);
      return payload;
    },
    /** An agent.message carried this message's text. */
    messageExpressed(message: Message) {
      expressed.messages.set(message.id, textOf(message));
    },
  };
}