Skip to content

A personal agent with a browser, terminal, files, and work that keeps going built with CopilotKit and AG-UI.

TypeScript
13.6 KB
Raw Blame
import { createHash, randomUUID } from "node:crypto";
import {
  type JevAction,
  type JevOption,
  type JevPanel,
  type JevToolResult,
  jevActionSchema,
  jevOptionSchema,
  jevPanelSchema,
} from "../../../../packages/domain/src/jev.ts";
import type { Store } from "../db.ts";
import { type JevAdapter, rankJevOptions } from "./adapter.ts";

export type PresentChoicesInput = {
  /** The person's latest message; the tool always supplies it, direct callers fall back to `message`. */
  userMessage?: string;
  message: string;
  context: string;
  title: string;
  control: "clarification" | "comparison";
  options: Array<Omit<JevOption, "id"> & { id?: string }>;
  refinementPanelId?: string;
};
type PanelRecord = { id: string; panel: JevPanel; candidates: JevOption[] };
type ThreadRecord = {
  id: string;
  revision: number;
  generation: number;
  currentPanelId?: string | null;
  selectedId?: string | null;
  /** The panel a new user turn retired; only that turn may still refine it. */
  retiredPanelId?: string | null;
  retiredTurnId?: string | null;
};
/** Whether `panelId` may be refined by `turnId`: it is current, or this turn just retired it. */
function refinable(head: ThreadRecord | null | undefined, panelId: string, turnId: string) {
  return (
    !!head &&
    (head.currentPanelId === panelId ||
      (head.retiredPanelId === panelId && head.retiredTurnId === turnId))
  );
}
export type JevHeadSnapshot = {
  currentPanelId: string;
  revision: number;
  selectedId: string | null;
};
export class JevService {
  constructor(
    private readonly deps: { store: Store; adapter: JevAdapter; mode: "sample" | "live" },
  ) {}
  private get store() {
    return this.deps.store;
  }
  private async reserve(
    owner: string,
    threadId: string,
    turnId: string,
    refinementPanelId?: string,
  ): Promise<ThreadRecord> {
    await this.store.insertIfAbsent(owner, "jev_threads", {
      id: threadId,
      revision: 0,
      generation: 0,
    });
    for (let attempt = 0; attempt < 20; attempt++) {
      const current = await this.store.get<ThreadRecord>(owner, "jev_threads", threadId);
      if (!current) throw new Error("Choices thread is unavailable");
      if (refinementPanelId && !refinable(current, refinementPanelId, turnId))
        throw new Error("The earlier choices have been superseded");
      const updated = await this.store.compareAndSwap<ThreadRecord>(
        owner,
        "jev_threads",
        threadId,
        {
          generation: current.generation,
          ...(!refinementPanelId
            ? {}
            : current.currentPanelId === refinementPanelId
              ? { currentPanelId: refinementPanelId }
              : { retiredPanelId: refinementPanelId, retiredTurnId: turnId }),
        },
        { generation: current.generation + 1 },
      );
      if (updated) return updated;
    }
    throw new Error("Choices thread changed too many times; please retry");
  }
  async currentPanel(owner: string, threadId: string): Promise<JevPanel | null> {
    const head = await this.store.get<ThreadRecord>(owner, "jev_threads", threadId);
    if (!head?.currentPanelId) return null;
    const record = await this.store.get<PanelRecord>(owner, "jev_panels", head.currentPanelId);
    return record?.panel ?? null;
  }
  async headSnapshot(owner: string, threadId: string): Promise<JevHeadSnapshot | null> {
    const head = await this.store.get<ThreadRecord>(owner, "jev_threads", threadId);
    if (!head?.currentPanelId) return null;
    return {
      currentPanelId: head.currentPanelId,
      revision: head.revision,
      selectedId: head.selectedId ?? null,
    };
  }
  /** Retires the snapshot's panel on behalf of `turnId`, unless the head moved meanwhile. */
  async expireIfUnchanged(
    owner: string,
    threadId: string,
    snapshot: JevHeadSnapshot | null,
    turnId: string,
  ): Promise<boolean> {
    if (!snapshot) return false;
    const head = await this.store.get<ThreadRecord>(owner, "jev_threads", threadId);
    if (
      !head ||
      head.currentPanelId !== snapshot.currentPanelId ||
      head.revision !== snapshot.revision ||
      (head.selectedId ?? null) !== snapshot.selectedId
    )
      return false;
    return !!(await this.store.compareAndSwap<ThreadRecord>(
      owner,
      "jev_threads",
      threadId,
      {
        generation: head.generation,
        revision: snapshot.revision,
        currentPanelId: snapshot.currentPanelId,
        selectedId: snapshot.selectedId,
      },
      {
        generation: head.generation + 1,
        revision: head.generation + 1,
        currentPanelId: null,
        selectedId: null,
        retiredPanelId: snapshot.currentPanelId,
        retiredTurnId: turnId,
      },
    ));
  }
  async candidateSources(
    owner: string,
    threadId: string,
    turnId: string,
    refinementPanelId: string,
  ): Promise<string[]> {
    const head = await this.store.get<ThreadRecord>(owner, "jev_threads", threadId);
    const record = await this.store.get<PanelRecord>(owner, "jev_panels", refinementPanelId);
    if (
      !refinable(head, refinementPanelId, turnId) ||
      record?.panel.threadId !== threadId ||
      (this.deps.mode === "live" && record.panel.mode !== "live")
    )
      throw new Error("The earlier choices are unavailable or superseded");
    return [
      ...new Set(record.candidates.flatMap((option) => option.sources.map((source) => source.url))),
    ];
  }
  async createPanel(
    owner: string,
    threadId: string,
    turnId: string,
    input: PresentChoicesInput,
    signal: AbortSignal,
  ): Promise<JevToolResult> {
    signal.throwIfAborted();
    const previous = input.refinementPanelId
      ? await this.store.get<PanelRecord>(owner, "jev_panels", input.refinementPanelId)
      : null;
    const priorHead = input.refinementPanelId
      ? await this.store.get<ThreadRecord>(owner, "jev_threads", threadId)
      : null;
    if (
      input.refinementPanelId &&
      (!previous ||
        previous.panel.threadId !== threadId ||
        !refinable(priorHead, input.refinementPanelId, turnId))
    )
      throw new Error("The earlier choices are unavailable or superseded");
    const candidates = previous
      ? previous.candidates
      : input.options.map((candidate) => {
          const id =
            candidate.id ??
            createHash("sha256")
              .update(
                JSON.stringify({
                  label: candidate.label,
                  details: candidate.details,
                  sources: candidate.sources,
                }),
              )
              .digest("hex")
              .slice(0, 32);
          return jevOptionSchema.parse({ ...candidate, id });
        });
    if (
      candidates.length < 1 ||
      candidates.length > 12 ||
      new Set(candidates.map((o) => o.id)).size !== candidates.length
    )
      throw new Error("Choices need 1–12 distinct options");
    if (input.control === "comparison" && candidates.some((o) => o.sources.length === 0))
      throw new Error("Comparison choices need sources");
    const generation = await this.reserve(owner, threadId, turnId, input.refinementPanelId);
    const priorSelectedId = generation.selectedId ?? undefined;
    const decision = await this.deps.adapter.decide(
      {
        userMessage: input.userMessage ?? input.message,
        message: input.message,
        context: input.context,
        options: candidates,
        allowedControls: [input.control, "agent"],
        selectedId: priorSelectedId,
      },
      signal,
    );
    signal.throwIfAborted();
    if (decision.control === "agent") {
      const head = await this.store.compareAndSwap<ThreadRecord>(
        owner,
        "jev_threads",
        threadId,
        {
          generation: generation.generation,
          revision: generation.revision,
          ...(generation.currentPanelId !== undefined
            ? { currentPanelId: generation.currentPanelId }
            : {}),
          ...(generation.selectedId !== undefined ? { selectedId: generation.selectedId } : {}),
        },
        {
          revision: generation.generation,
          currentPanelId: null,
          selectedId: null,
          retiredPanelId: null,
          retiredTurnId: null,
        },
      );
      if (!head)
        return { panel: null, error: "These choices were superseded by a newer response." };
      return { panel: null };
    }
    if (decision.control !== input.control) throw new Error("Jev returned an unexpected control");
    const ranked = rankJevOptions(candidates, decision);
    const visible = decision.control === "comparison" ? ranked.slice(0, 3) : ranked;
    const preferredId =
      previous && priorSelectedId && ranked.some((option) => option.id === priorSelectedId)
        ? priorSelectedId
        : undefined;
    if (preferredId && !visible.some((option) => option.id === preferredId)) {
      const preferred = ranked.find((option) => option.id === preferredId);
      if (preferred) visible[visible.length - 1] = preferred;
    }
    const panel = jevPanelSchema.parse({
      id: randomUUID(),
      threadId,
      turnId,
      candidateSetVersion: generation.generation,
      type: decision.control,
      title: input.title,
      options: visible,
      preferredId,
      mode: this.deps.mode,
    });
    signal.throwIfAborted();
    await this.store.insertIfAbsent(owner, "jev_panels", { id: panel.id, panel, candidates });
    signal.throwIfAborted();
    const head = await this.store.compareAndSwap<ThreadRecord>(
      owner,
      "jev_threads",
      threadId,
      {
        generation: generation.generation,
        revision: generation.revision,
        ...(generation.currentPanelId !== undefined
          ? { currentPanelId: generation.currentPanelId }
          : {}),
        ...(generation.selectedId !== undefined ? { selectedId: generation.selectedId } : {}),
      },
      {
        revision: generation.generation,
        currentPanelId: panel.id,
        selectedId: null,
        retiredPanelId: null,
        retiredTurnId: null,
      },
    );
    if (!head) return { panel: null, error: "These choices were superseded by a newer response." };
    return { panel };
  }
  async select(
    owner: string,
    threadId: string,
    rawAction: JevAction,
  ): Promise<{ continuation: string; panel: JevPanel }> {
    const action = jevActionSchema.parse(rawAction);
    if (action.threadId !== threadId)
      throw new Error("This choice belongs to another conversation");
    const record = await this.store.get<PanelRecord>(owner, "jev_panels", action.panelId);
    if (
      !record ||
      record.panel.threadId !== threadId ||
      record.panel.candidateSetVersion !== action.candidateSetVersion
    )
      throw new Error("This choice is unavailable or out of date");
    const option = record.candidates.find((o) => o.id === action.optionId);
    if (!option || !record.panel.options.some((o) => o.id === action.optionId))
      throw new Error("This option is unavailable");
    const head = await this.store.get<ThreadRecord>(owner, "jev_threads", threadId);
    if (
      !head ||
      head.revision !== action.candidateSetVersion ||
      head.currentPanelId !== action.panelId
    )
      throw new Error("These choices have been superseded");
    if (head.selectedId && head.selectedId !== action.optionId)
      throw new Error("A different choice was already selected");
    if (!head.selectedId) {
      const claimed = await this.store.compareAndSwap<ThreadRecord>(
        owner,
        "jev_threads",
        threadId,
        { revision: head.revision, currentPanelId: action.panelId, selectedId: null },
        { selectedId: action.optionId },
      );
      if (!claimed) {
        const reread = await this.store.get<ThreadRecord>(owner, "jev_threads", threadId);
        if (reread?.selectedId !== action.optionId || reread?.currentPanelId !== action.panelId)
          throw new Error("This choice has changed");
      }
    }
    return {
      continuation: `I choose “${option.label}” from ${record.panel.type} choices. Continue with that preference.`,
      panel: { ...record.panel, selectedId: option.id },
    };
  }
  async noteEvidence(
    owner: string,
    threadId: string,
    runId: string,
    kind: "mail" | "web",
    reference: string,
    text?: string,
  ): Promise<void> {
    const id = `${threadId}:${runId}:${kind}:${createHash("sha256").update(reference).digest("hex")}`;
    if (kind === "web") {
      if (!text?.trim()) return;
      await this.store.put(owner, "jev_evidence", {
        id,
        threadId,
        runId,
        kind,
        reference,
        text: text.slice(0, 30_000),
      });
      return;
    }
    await this.store.insertIfAbsent(owner, "jev_evidence", {
      id,
      threadId,
      runId,
      kind,
      reference,
    });
    await this.store.insertIfAbsent(owner, "jev_mail_evidence", { id: `${threadId}:${runId}` });
  }
  async hasEvidence(
    owner: string,
    threadId: string,
    runId: string,
    kind: "mail" | "web",
    reference: string,
  ): Promise<boolean> {
    const id = `${threadId}:${runId}:${kind}:${createHash("sha256").update(reference).digest("hex")}`;
    return !!(await this.store.get(owner, "jev_evidence", id));
  }
  async hasAnyMailEvidence(owner: string, threadId: string, runId: string): Promise<boolean> {
    return !!(await this.store.get(owner, "jev_mail_evidence", `${threadId}:${runId}`));
  }
  async evidenceText(
    owner: string,
    threadId: string,
    runId: string,
    kind: "web",
    reference: string,
  ): Promise<string | null> {
    const id = `${threadId}:${runId}:${kind}:${createHash("sha256").update(reference).digest("hex")}`;
    const record = await this.store.get<{ text?: string }>(owner, "jev_evidence", id);
    return record?.text?.trim() ? record.text : null;
  }
}