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.

14.8 KB
Raw Blame
import { CopilotKitIntelligence } from "@copilotkit/runtime/v2";
import {
  AUTOMATIC_LEARNING_CONTAINER_ID,
  type LearningAutoAssignState,
} from "@openbot/shared/learning";
import {
  type AuditStore,
  DEPLOYMENT_INITIATOR,
  recordAuditEvent,
} from "../audit";
import type { LearningSettingsStore } from "./settings";

/** What asking Intelligence about one container found. */
export type ContainerProbe =
  | "present"
  | "absent"
  | "not_entitled"
  | "unavailable";

/**
 * Read a learned-skills error into whether the container is there.
 *
 * The runtime key cannot list or create Learning containers: Intelligence serves those routes only
 * to a person's session or CLI login. What it can do is read a container's published Skills, and
 * that read is scoped to the key's own project, so it answers the one question this needs without
 * a side effect. A container nobody has published to yet still exists: Intelligence says the
 * revision is missing or delivery is off, not that the container is.
 */
export function classifyProbeError(error: unknown): ContainerProbe {
  const code =
    error !== null && typeof error === "object" && "code" in error
      ? (error as { code: unknown }).code
      : undefined;
  if (code === "CONTAINER_NOT_FOUND") return "absent";
  if (
    code === "REVISION_NOT_FOUND" ||
    code === "DELIVERY_DISABLED" ||
    code === "REVISION_REVOKED"
  )
    return "present";
  if (code === "ENTITLEMENT_REQUIRED") return "not_entitled";
  return "unavailable";
}

/** Ask whether `containerId` exists in the project the runtime key belongs to. */
export async function probeLearningContainer(
  client: Pick<CopilotKitIntelligence, "getLearnedSkillsSnapshot">,
  containerId: string,
  timeoutMs = 5_000,
): Promise<ContainerProbe> {
  try {
    await client.getLearnedSkillsSnapshot({
      containerId,
      signal: AbortSignal.timeout(timeoutMs),
    });
    return "present";
  } catch (error) {
    return classifyProbeError(error);
  }
}

/** The organization and project a runtime key belongs to, by slug. */
export type KeyProject = { organizationSlug: string; projectSlug: string };

/**
 * Which project a runtime key belongs to, read from the Learning link Intelligence returns for it.
 *
 * The key cannot name its own project directly. The Inspector projection it can read carries a link
 * to the project's Learning page, `/o/<organization>/<project>/learning`, and that is enough for a
 * helper holding a person's login to refuse to create a container in some other project. Anything
 * unreadable is `undefined`, and callers treat that as "cannot prove it".
 */
export async function keyProject(
  client: Pick<CopilotKitIntelligence, "getInspectorLearning">,
  timeoutMs = 10_000,
): Promise<KeyProject | undefined> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    // The Inspector read takes no signal, so the deadline races it.
    const snapshot = await Promise.race([
      client.getInspectorLearning({}),
      new Promise<never>((_, reject) => {
        timer = setTimeout(
          () => reject(new Error("Inspector read timed out")),
          timeoutMs,
        );
      }),
    ]);
    const [o, organizationSlug, projectSlug, learning] = new URL(
      snapshot.links.learning,
    ).pathname
      .split("/")
      .filter(Boolean)
      .map(decodeURIComponent);
    if (
      o !== "o" ||
      learning !== "learning" ||
      !organizationSlug ||
      !projectSlug
    )
      return undefined;
    return { organizationSlug, projectSlug };
  } catch {
    return undefined;
  } finally {
    clearTimeout(timer);
  }
}

/** A runtime key's project by slug and by name: everything the key can say about where it lives. */
export type KeyIdentity = KeyProject & {
  organizationName: string;
  projectName: string;
};

/**
 * The key's project slugs (see `keyProject`) and the organization and project names its Inspector
 * metadata carries. The names are what a CopilotKit CLI login can be compared on: the CLI reports
 * its organization by name and Clerk ID, never by slug. Anything unreadable is `undefined`.
 */
export async function keyIdentity(
  client: Pick<
    CopilotKitIntelligence,
    "getInspectorLearning" | "getInspectorMetadata"
  >,
  timeoutMs = 10_000,
): Promise<KeyIdentity | undefined> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    const [slugs, metadata] = await Promise.all([
      keyProject(client, timeoutMs),
      Promise.race([
        client.getInspectorMetadata(),
        new Promise<never>((_, reject) => {
          timer = setTimeout(
            () => reject(new Error("Inspector metadata timed out")),
            timeoutMs,
          );
        }),
      ]),
    ]);
    const identity = metadata?.identity;
    if (!slugs || !identity?.organizationName || !identity.projectName)
      return undefined;
    return {
      ...slugs,
      organizationName: identity.organizationName,
      projectName: identity.projectName,
    };
  } catch {
    return undefined;
  } finally {
    clearTimeout(timer);
  }
}

/** A client holding only a runtime key, for helpers that run without the server. */
export function runtimeKeyClient(
  apiUrl: string,
  apiKey: string,
  wsUrl?: string,
) {
  return new CopilotKitIntelligence({
    apiUrl,
    apiKey,
    ...(wsUrl ? { wsUrl } : {}),
  });
}

/** What creating the container with a credential that can did. `skipped`: nothing here could. */
export type ContainerCreation = "present" | "created" | "skipped";

export type LearningAutoAssign = {
  /** Check now, unless a check is already running, and return what it found. Never throws. */
  check(): Promise<LearningAutoAssignState>;
  /**
   * Admin's "Create it now": try the configured credential again, whatever earlier attempts found,
   * then check. Never throws; a failure comes back as the state's `createError`.
   */
  createNow(): Promise<LearningAutoAssignState>;
  /** Start a check in the background if none ran within the last `minIntervalMs`. */
  kick(): void;
  /** The last answer, without asking. */
  state(): LearningAutoAssignState;
  /** Check at boot, then keep checking every `retryMs` until there is nothing left to do. */
  start(): void;
  stop(): void;
};

/** How often a deployment with no container asks again, so one created later is picked up. */
const RETRY_MS = 10 * 60_000;
/** The shortest gap between background checks started by page loads and turns. */
const MIN_INTERVAL_MS = 60_000;

/**
 * Assign this project's `openbot` Learning container as the default when nobody has chosen one.
 *
 * Automatic Learning is on by default, but it collects and delivers nothing until a container is
 * assigned, and assigning one used to take a helper script or a trip to Admin. This closes that gap
 * for every deployment whose Intelligence project already has the container:
 *
 * - It never overrides a choice. A saved Admin setting of any kind, including a saved off, and a
 *   container named in the environment both mean there is nothing to do.
 * - It creates the container only through `create`, with a credential that can (a service token on
 *   a local evaluation install, or a CopilotKit CLI login on this machine; see
 *   learning/ensure-container.ts), once per process unless Admin asks again. The runtime key cannot.
 *   With no such credential it says exactly what to run, once, in the log and on the Admin page.
 * - It is safe on many replicas: the write is a conditional insert, so the first one wins and the
 *   rest see a saved setting. Only the winner writes the audit row.
 * - It never blocks startup or a turn. Every failure is logged once per kind and tried again later.
 */
export function createLearningAutoAssign(options: {
  /** False when the operator switched this off or the environment names a container. */
  enabled: boolean;
  store: Pick<LearningSettingsStore, "saved" | "adoptDefault">;
  probe: (containerId: string) => Promise<ContainerProbe>;
  /** Create the container with a credential that can. Absent when this deployment holds none. */
  create?: () => Promise<ContainerCreation>;
  /** Exactly what an operator runs when the container is absent and nothing here created it. */
  instructions?: string;
  audit?: AuditStore;
  containerId?: string;
  retryMs?: number;
  minIntervalMs?: number;
  now?: () => number;
  log?: (entry: Record<string, unknown>) => void;
}): LearningAutoAssign {
  const containerId = options.containerId ?? AUTOMATIC_LEARNING_CONTAINER_ID;
  const now = options.now ?? Date.now;
  const minIntervalMs = options.minIntervalMs ?? MIN_INTERVAL_MS;
  const log = options.log ?? ((entry) => console.warn(JSON.stringify(entry)));
  let current: LearningAutoAssignState = options.enabled
    ? { state: "pending" }
    : { state: "off" };
  let running: Promise<LearningAutoAssignState> | undefined;
  let lastStartedAt = Number.NEGATIVE_INFINITY;
  let timer: ReturnType<typeof setInterval> | undefined;
  const logged = new Set<string>();

  const settled = (state: LearningAutoAssignState) =>
    state.state === "off" ||
    state.state === "saved" ||
    state.state === "assigned";
  const once = (kind: string, entry: Record<string, unknown>) => {
    if (logged.has(kind)) return;
    logged.add(kind);
    log({ type: "learning-auto-assign", outcome: kind, containerId, ...entry });
  };

  const instructions =
    options.instructions ??
    `Run bun scripts/setup-learning.ts, or create a container with ID "${containerId}" in Intelligence; OpenBot assigns it within ${Math.round((options.retryMs ?? RETRY_MS) / 60_000)} minutes.`;
  /** Whether this process already tried `create`: once at boot, again only when Admin asks. */
  let createTried = false;
  let createError: string | undefined;

  /** Create it with the configured credential, once. True when it is there now. */
  const tryCreate = async (): Promise<boolean> => {
    if (!options.create || createTried) return false;
    createTried = true;
    try {
      const result = await options.create();
      createError = undefined;
      if (result === "skipped") return false;
      log({
        type: "learning-auto-assign",
        outcome: result === "created" ? "container_created" : "container_found",
        containerId,
        message:
          result === "created"
            ? `Created the "${containerId}" Learning container with the configured credential.`
            : `The "${containerId}" Learning container is there now.`,
      });
      return true;
    } catch (error) {
      createError =
        error instanceof Error
          ? error.message.slice(0, 500)
          : "The container could not be created.";
      once("create_failed", { message: createError });
      return false;
    }
  };

  const absent = (): LearningAutoAssignState => ({
    state: "absent",
    containerId,
    instructions,
    canCreate: Boolean(options.create),
    ...(createError ? { createError } : {}),
  });

  const run = async (): Promise<LearningAutoAssignState> => {
    if (!options.enabled) return { state: "off" };
    if (await options.store.saved()) return { state: "saved" };
    let found = await options.probe(containerId);
    if (found === "absent" && (await tryCreate()))
      found = await options.probe(containerId);
    if (found === "absent") {
      once("absent", {
        message: `This Intelligence project has no "${containerId}" Learning container, so Automatic Learning collects nothing yet. ${instructions}`,
      });
      return absent();
    }
    if (found === "not_entitled") {
      once("not_entitled", {
        message:
          "This Intelligence project's plan does not include Learning, so no container was assigned.",
      });
      return { state: "not_entitled" };
    }
    if (found === "unavailable") {
      once("unavailable", {
        message:
          "Intelligence could not be asked about the Learning container. OpenBot tries again.",
      });
      return { state: "unavailable" };
    }
    if (!(await options.store.adoptDefault({ containerId })))
      return { state: "saved" };
    if (options.audit)
      await recordAuditEvent(options.audit, {
        eventType: "configuration.changed",
        targetType: "learning",
        initiator: DEPLOYMENT_INITIATOR,
        payload: {
          change: "default_container_assigned_automatically",
          enabled: true,
          defaultContainerId: containerId,
          botMappingCount: 0,
        },
      });
    log({
      type: "learning-auto-assign",
      outcome: "assigned",
      containerId,
      message: `Assigned the "${containerId}" Learning container as the default. Change it in Admin → Automatic Learning.`,
    });
    return { state: "assigned", containerId };
  };

  const check = (): Promise<LearningAutoAssignState> => {
    if (settled(current)) return Promise.resolve(current);
    if (running) return running;
    lastStartedAt = now();
    running = run()
      .catch((error: unknown) => {
        once("error", {
          errorType: error instanceof Error ? error.name : typeof error,
          message:
            "Automatic Learning container assignment failed. OpenBot tries again.",
        });
        return { state: "unavailable" } as LearningAutoAssignState;
      })
      .then((state) => {
        current = state;
        if (settled(state)) stopTimer();
        return state;
      })
      .finally(() => {
        running = undefined;
      });
    return running;
  };

  const stopTimer = () => {
    if (timer) clearInterval(timer);
    timer = undefined;
  };

  return {
    check,
    async createNow() {
      // Wait out a check already running, so this attempt is not swallowed by its result.
      if (running) await running;
      // Off, saved or assigned: there is nothing for a container to be assigned to.
      if (settled(current)) return current;
      createTried = false;
      return check();
    },
    kick() {
      if (settled(current) || running) return;
      if (now() - lastStartedAt < minIntervalMs) return;
      void check();
    },
    state: () => current,
    start() {
      if (!options.enabled) return;
      void check();
      timer = setInterval(() => void check(), options.retryMs ?? RETRY_MS);
      // Never keep the process alive for this alone.
      timer.unref?.();
    },
    stop: stopTimer,
  };
}

/**
 * The settings store, nudging automatic assignment whenever a reader finds no default.
 *
 * Every reader of Learning settings goes through here (a turn binding its thread, Admin, skill
 * delivery), so a deployment whose container appeared after boot, or whose boot check could not
 * reach Intelligence, is assigned on its next use rather than only on the timer. The nudge never
 * waits and is rate-limited inside `kick`.
 */
export function withLearningAutoAssign<T extends LearningSettingsStore>(
  store: T,
  autoAssign: LearningAutoAssign,
): T {
  return {
    ...store,
    async read() {
      const settings = await store.read();
      if (settings.enabled && settings.defaultTarget === null)
        autoAssign.kick();
      return settings;
    },
  };
}