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.

8.2 KB
Raw Blame
import type {
  CopilotRuntimeHooks,
  GetTrajectoryLearningContainerIds,
} from "@copilotkit/runtime/v2";
import { eq } from "drizzle-orm";
import type { AuditStore } from "../audit";
import type { AuthenticatedActor, RoleRepository } from "../auth/guards";
import {
  ORGANIZATION_SESSION_COOKIE,
  ORGANIZATION_SESSION_MAX_AGE_SECONDS,
  organizationCookieExpiresAt,
} from "../auth/organization";
import type { DeploymentConfig } from "../config";
import { decryptSecret, encryptSecret } from "../credentials";
import type { Database } from "../db/client";
import { users } from "../db/schema";
import type { PersonalLearningSpaces } from "../learning/personal-space";
import type { PeopleStore } from "../people/store";
import {
  createRecorderConnectionStore,
  type RecorderConnectionLifetime,
} from "./connections";
import { allowedExtensionIds } from "./extension-origins";
import {
  createRecorderResolver,
  type RecorderMode,
  type RecorderRefusalSink,
  type RecorderResolver,
} from "./guard";
import { createRecorderRefusalAudit } from "./refusal-audit";
import type { RecorderRouteDeps } from "./routes";
import { createRecorderSignOut, type SignOutRecorders } from "./sign-out";
import { createTrajectoryBindingStore } from "./trajectory-bindings";
import {
  createTrajectoryConnectHook,
  createTrajectoryLearningSelector,
  createTrajectoryRefusalAudit,
} from "./trajectory-gate";

/** What createApp's `coworker.recorder` takes. */
export type RecorderExtensionDeps = Omit<
  RecorderRouteDeps,
  "requireUser" | "requireRecorder" | "auditStore"
> & {
  resolve: RecorderResolver;
  onRefused: RecorderRefusalSink;
  /** Ends a person's Recorders when their sign-in here ends (recorder/sign-out.ts): what every such path calls. */
  signOut: SignOutRecorders;
};

/** How long the Recorder's popup waits for the person's Learning space: the capture pass's own budget. */
const LEARNING_SPACE_WAIT_MS = 4_000;

/** The value of one cookie in a Cookie header, or undefined. */
function cookieValue(header: string, name: string): string | undefined {
  for (const part of header.split(";")) {
    const at = part.indexOf("=");
    if (at > 0 && part.slice(0, at).trim() === name) {
      return part.slice(at + 1).trim();
    }
  }
  return undefined;
}

/** Better Auth's session lifetime, which a deployment that signs people in through it must say: a connection with no
 * lifetime would never end. */
function betterAuthLifetime(ms: number | undefined): number {
  if (ms === undefined || !Number.isFinite(ms) || ms <= 0) {
    throw new Error(
      "The Recorder needs Better Auth's session lifetime to bound its connections.",
    );
  }
  return ms;
}

/**
 * Every piece of Recorder wiring `index.ts` would otherwise hold, so tests build exactly what `index.ts` builds
 * (`index.ts` cannot be imported by a test: it loads the config and starts the server at top level).
 */
export function createRecorderExtension(deps: {
  config: DeploymentConfig;
  database: Database;
  organizationAuth:
    | {
        verifySessionQuietly(
          cookieHeader: string,
        ): Promise<AuthenticatedActor | null>;
      }
    | undefined;
  roleRepository: RoleRepository;
  peopleStore: Pick<PeopleStore, "isRevoked">;
  /** Each person's own Learning space, which every recording they make joins. */
  personalSpaces: PersonalLearningSpaces;
  auditStore: AuditStore;
  /**
   * How long a Better Auth session lasts here unused, in milliseconds (auth/index.ts `sessionLifetimeMs`, read from the
   * auth instance): a Recorder connection lasts as long. Required where people sign in through Better Auth; single-user
   * and organization mode take their lifetime from elsewhere.
   */
  sessionLifetimeMs?: number;
  /**
   * Where a connection's own rows go, given the transaction that makes or ends it (connections.ts): index.ts passes
   * `createAuditStore` over it. Absent, `auditStore` as it is: a test's own, which keeps a row whether or not the
   * transaction commits.
   */
  auditFor?: (executor: Database) => AuditStore;
}): RecorderExtensionDeps & {
  /** The capture pass, for `mountCopilotRuntime`: its gate (an onBeforeHandler hook) and its Learning space selector. */
  trajectoryCapture: {
    gate: NonNullable<CopilotRuntimeHooks["onBeforeHandler"]>;
    selectLearningContainers: GetTrajectoryLearningContainerIds;
  };
} {
  const { config, database, organizationAuth } = deps;
  const trajectoryBindings = createTrajectoryBindingStore(database);
  const { personalSpaces } = deps;

  /*
   * A connection is a sign-in of its own, so it lasts as the person's sign-in here does. Better Auth's session ends once
   * it has gone unused for its `expiresIn`; an organization session is a cookie that ends at its own expiry, and the
   * connection carries a sealed copy of it, which must not outlive the cookie. A single-user OpenBot has no sign-in.
   */
  const lifetime: RecorderConnectionLifetime = config.singleUser
    ? null
    : organizationAuth
      ? {
          kind: "organization",
          ms: ORGANIZATION_SESSION_MAX_AGE_SECONDS * 1_000,
        }
      : { kind: "idle", ms: betterAuthLifetime(deps.sessionLifetimeMs) };
  const connections = createRecorderConnectionStore(database, {
    lifetime,
    auditFor: deps.auditFor ?? (() => deps.auditStore),
  });

  const mode: RecorderMode = config.singleUser
    ? { kind: "single-user" }
    : organizationAuth
      ? {
          kind: "organization",
          session: (cookie) => organizationAuth.verifySessionQuietly(cookie),
          unseal: (value) => decryptSecret(config.keyEncryptionKey, value),
        }
      : {
          kind: "better-auth",
          roles: deps.roleRepository,
          isRevoked: (email) => deps.peopleStore.isRevoked(email),
          allowedEmailDomains: config.auth?.allowedEmailDomains ?? [],
        };

  const userRow = async (userId: string) =>
    (
      await database
        .select({
          id: users.id,
          email: users.email,
          name: users.name,
          image: users.image,
        })
        .from(users)
        .where(eq(users.id, userId))
        .limit(1)
    )[0] ?? null;
  const resolve = createRecorderResolver({
    connections,
    mode,
    user: userRow,
    endConnection: async (userId, connectionId) => {
      await connections.revoke(
        userId,
        connectionId,
        "signed_out",
        "organization",
      );
    },
  });

  // Sealed with when the cookie itself expires, which the connection made from it keeps and ends at.
  const sealOrganizationSession: RecorderExtensionDeps["sealOrganizationSession"] =
    organizationAuth
      ? async (cookieHeader) => {
          const value = cookieHeader
            ? cookieValue(cookieHeader, ORGANIZATION_SESSION_COOKIE)
            : undefined;
          return value
            ? {
                sealed: await encryptSecret(config.keyEncryptionKey, value),
                expiresAt: organizationCookieExpiresAt(value),
              }
            : null;
        }
      : async () => null;

  return {
    connections,
    allowedExtensionIds: () => allowedExtensionIds(config),
    // Bounded like a capture pass, so the popup is not held by a slow Intelligence; a creation it started goes on.
    learningSpace: (actor) =>
      personalSpaces.state(
        actor.id,
        AbortSignal.timeout(LEARNING_SPACE_WAIT_MS),
      ),
    // Made when the browser connects, so a space only a slow credential can make is there before the first recording.
    onConnected: (userId) => personalSpaces.kick(userId),
    user: async (userId) => {
      const row = await userRow(userId);
      return row
        ? { id: row.id, email: row.email, name: row.name?.trim() || row.email }
        : null;
    },
    sealOrganizationSession,
    resolve,
    onRefused: createRecorderRefusalAudit(deps.auditStore),
    signOut: createRecorderSignOut({
      connections,
      auditStore: deps.auditStore,
    }),
    trajectoryCapture: {
      gate: createTrajectoryConnectHook({
        resolveRecorder: resolve,
        bind: trajectoryBindings.bind,
        audit: createTrajectoryRefusalAudit(deps.auditStore),
      }),
      selectLearningContainers: createTrajectoryLearningSelector({
        isBoundTo: trajectoryBindings.isBoundTo,
        personalSpace: personalSpaces,
      }),
    },
  };
}