@copilotkit/learning 0.0.1

package/src/trajectory-collector.ts

@@ -0,0 +1,193 @@
+import { installClickCapture } from "./clicks";
+import { installNavigationCapture } from "./navigation";
+import { installInputCapture } from "./inputs";
+import { installNetworkCapture } from "./network";
+import { createRedactor } from "./redact";
+import { toRoute } from "./routes";
+import { BUILT_IN_EVENT_NAMES } from "./types";
+import type {
+  JsonValue,
+  TrajectoryCaptureOptions,
+  TrajectoryCollector,
+  TrajectoryEvent,
+} from "./trajectory-types";
+
+export const MAX_TRAJECTORY_EVENT_BYTES = 16 * 1024;
+const RESERVED_NAMES = new Set<string>(BUILT_IN_EVENT_NAMES);
+
+function isJson(
+  value: unknown,
+  ancestors = new Set<object>(),
+): value is JsonValue {
+  if (typeof value === "string") return !value.includes("\0");
+  if (value === null || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value !== "object" || ancestors.has(value)) return false;
+  if (
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) !== Object.prototype &&
+    Object.getPrototypeOf(value) !== null
+  )
+    return false;
+  ancestors.add(value);
+  if (
+    !Array.isArray(value) &&
+    Object.keys(value).some((key) => key.includes("\0"))
+  )
+    return false;
+  const values = Array.isArray(value) ? value : Object.values(value);
+  for (const item of values) {
+    if (!isJson(item, ancestors)) return false;
+  }
+  ancestors.delete(value);
+  return true;
+}
+
+/**
+ * Captures outside-chat activity as plain AG-UI events, without a send queue.
+ * Core starts this collector only after authentication and channel join.
+ */
+export function createTrajectoryCollector(
+  options: TrajectoryCaptureOptions & {
+    send: (event: TrajectoryEvent) => void;
+  },
+): TrajectoryCollector {
+  let active = false;
+  let uninstalls: (() => void)[] = [];
+
+  const report = (code: string, message: string) => {
+    try {
+      options.onError?.({ code, message });
+    } catch {
+      // Diagnostic callbacks must not interrupt the host app.
+    }
+  };
+
+  const getRoute = () => toRoute(location.pathname);
+
+  const record = (name: string, value: JsonValue) => {
+    if (!active) return;
+    let payload: TrajectoryEvent;
+    try {
+      const event: TrajectoryEvent = {
+        type: "CUSTOM",
+        name,
+        timestamp: Date.now(),
+        value,
+      };
+      const kept =
+        options.beforeSend === undefined ? event : options.beforeSend(event);
+      if (kept === null || !active) return;
+      if (
+        kept.type !== "CUSTOM" ||
+        typeof kept.name !== "string" ||
+        !kept.name.trim() ||
+        kept.name.length > 200 ||
+        kept.name.includes("\0") ||
+        !Number.isFinite(kept.timestamp) ||
+        kept.timestamp <= 0 ||
+        kept.timestamp >= 253_402_300_800_000 ||
+        !isJson(kept.value)
+      ) {
+        report(
+          "INVALID_EVENT",
+          "The event must contain a name, timestamp, and JSON value.",
+        );
+        return;
+      }
+      // Keep only the contract envelope and snapshot the value before delivery.
+      const serialized = JSON.stringify({
+        type: kept.type,
+        name: kept.name,
+        timestamp: kept.timestamp,
+        value: kept.value,
+      });
+      if (
+        new TextEncoder().encode(serialized).byteLength >
+        MAX_TRAJECTORY_EVENT_BYTES
+      ) {
+        report("EVENT_TOO_LARGE", "The serialized event exceeds 16 KiB.");
+        return;
+      }
+      payload = JSON.parse(serialized) as TrajectoryEvent;
+    } catch {
+      report("INVALID_EVENT", "The event could not be serialized as JSON.");
+      return;
+    }
+    try {
+      options.send(payload);
+    } catch {
+      report(
+        "PERSISTENCE_UNKNOWN",
+        "Event delivery failed. The event will not be retried.",
+      );
+    }
+  };
+
+  const capture = (name: string, value: Record<string, unknown>) => {
+    // Shared capture modules produce JSON; record validates and snapshots before sending.
+    record(name, value as JsonValue);
+  };
+
+  const stop = () => {
+    active = false;
+    const installed = uninstalls;
+    uninstalls = [];
+    for (const uninstall of installed) uninstall();
+  };
+
+  return {
+    start() {
+      if (active || typeof window === "undefined") return;
+      active = true;
+      // Native callers can emit developer events without browser observers.
+      if (typeof window.addEventListener !== "function") return;
+      // One per session: fields seen and values typed are forgotten on stop().
+      const redact = createRedactor();
+      try {
+        uninstalls.push(redact.watch());
+        if (options.capture?.clicks !== false) {
+          uninstalls.push(
+            installClickCapture({ emit: capture, getRoute, redact }),
+          );
+        }
+        if (options.capture?.navigation !== false) {
+          uninstalls.push(installNavigationCapture({ emit: capture, redact }));
+        }
+        if (options.capture?.inputs !== false) {
+          uninstalls.push(installInputCapture({ emit: capture, redact }));
+        }
+        if (options.capture?.network !== false) {
+          uninstalls.push(
+            installNetworkCapture({
+              emit: capture,
+              ignoreUrls: options.ignoreUrls ?? [],
+              redact,
+            }),
+          );
+        }
+        record("page", {
+          route: getRoute(),
+          url: redact.url(location.href),
+          title: document.title,
+          referrer: redact.url(document.referrer),
+        });
+      } catch {
+        stop();
+        report("CAPTURE_FAILED", "Browser capture could not start.");
+      }
+    },
+    stop,
+    emit(name, value) {
+      if (!active) return;
+      if (RESERVED_NAMES.has(name)) {
+        report(
+          "INVALID_EVENT",
+          "Use a developer event name, not a reserved capture name.",
+        );
+        return;
+      }
+      record(name, value);
+    },
+  };
+}

package/src/trajectory-types.ts

@@ -0,0 +1,50 @@
+import type { CaptureOptions } from "./types";
+
+/** JSON values accepted by developer events. */
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** One captured event. Core adds sequence metadata when it creates Gateway batches. */
+export interface TrajectoryEvent<V = JsonValue> {
+  type: "CUSTOM";
+  name: string;
+  timestamp: number;
+  value: V;
+}
+
+export type StartResult =
+  | { status: "started"; trajectoryId: string }
+  | { status: "error"; code: string };
+
+export interface ConnectionGrant {
+  joinToken: string;
+  realtime: { clientUrl: string; topic: string };
+}
+
+export interface TrajectoryError {
+  code: string;
+  message: string;
+}
+
+export interface TrajectoryCaptureOptions {
+  /** @deprecated Capture retains raw URLs; route templates no longer transform events. */
+  routes?: string[];
+  capture?: CaptureOptions;
+  /** Explicit app exclusions, plus Core transport URLs to prevent self-capture. */
+  ignoreUrls?: (string | RegExp)[];
+  /** Runs in the browser before validation and delivery. Return null to discard. */
+  beforeSend?: (event: TrajectoryEvent) => TrajectoryEvent | null;
+  /** Reports rejected events or delivery failures without interrupting the app. */
+  onError?: (error: TrajectoryError) => void;
+}
+
+export interface TrajectoryCollector {
+  start(): void;
+  stop(): void;
+  emit(name: string, value: JsonValue): void;
+}

package/src/types.ts

@@ -0,0 +1,98 @@
+/** Event names the collector and CopilotKit Core emit. `emit()` rejects them. */
+export const BUILT_IN_EVENT_NAMES = [
+  "page",
+  "navigation",
+  "click",
+  "input",
+  "network",
+  "thread.linked",
+  "agent.run",
+  "agent.message",
+  "tool.call",
+] as const;
+
+export type BuiltInEventName = (typeof BUILT_IN_EVENT_NAMES)[number];
+
+/** Replaces values that never leave the browser, even with full capture: passwords and credentials. */
+export const REDACTED = "[redacted]";
+
+/** One captured interaction, shaped as an AG-UI `CUSTOM` event. */
+export interface LearningEvent<V = Record<string, unknown>> {
+  type: "CUSTOM";
+  name: string;
+  value: V;
+  timestamp: number;
+}
+
+/** What a sink receives. The Trajectory scope sits on the batch, not on each event. */
+export interface LearningBatch {
+  trajectoryId: string;
+  learningContainerIds?: string[];
+  events: LearningEvent[];
+  /** Events lost since the previous batch (queue overflow or a failed send). */
+  dropped: number;
+}
+
+export interface SinkSendOptions {
+  /** True when the page is going away; use a transport that survives unload. */
+  beacon?: boolean;
+}
+
+/** Receives batches. `url`, when set, is never captured as a network event. */
+export type LearningSink = ((
+  batch: LearningBatch,
+  options?: SinkSendOptions,
+) => void | Promise<void>) & { readonly url?: string };
+
+export interface ClickTarget {
+  tag: string;
+  role: string | null;
+  action: string | null;
+  text: string;
+  attributes: Record<string, string>;
+  value?: string;
+  checked?: boolean;
+  selectedValues?: string[];
+  files?: { name: string; type: string; size: number; lastModified: number }[];
+  input: "pointer" | "keyboard";
+}
+
+/** Adds fields to a click event, from the element the user clicked. */
+export type EnrichFn = (target: Element) => Record<string, unknown> | undefined;
+
+export type Emit = (name: string, value: Record<string, unknown>) => void;
+
+export interface CaptureOptions {
+  clicks?: boolean;
+  navigation?: boolean;
+  network?: boolean;
+  inputs?: boolean;
+}
+
+export interface CollectorOptions {
+  sink: LearningSink;
+  /** @deprecated Capture retains raw URLs; route templates no longer transform events. */
+  routes?: string[];
+  /** URLs (prefix match on the absolute URL) or patterns that network capture skips. */
+  ignoreUrls?: (string | RegExp)[];
+  /** Turns capture modules on or off. All are on by default. */
+  capture?: CaptureOptions;
+  /** Runs last, in the browser. Return the event to send, or `null` to drop it. */
+  beforeSend?: (event: LearningEvent) => LearningEvent | null;
+  enrich?: EnrichFn;
+}
+
+export interface StartOptions {
+  trajectoryId: string;
+  learningContainerIds?: string[];
+}
+
+export interface Collector {
+  start(options: StartOptions): void;
+  stop(): void;
+  /** Developer events. Built-in names warn and are ignored. */
+  emit(name: string, value: Record<string, unknown>): void;
+  /** @internal For @copilotkit/core only: emits built-in names. */
+  ɵemit(name: BuiltInEventName, value: Record<string, unknown>): void;
+  readonly trajectoryId: string | null;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "@copilotkit/typescript-config/base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    // Browser-only package: no ambient @types from ancestor node_modules.
+    "types": [],
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules"]
+}

package/tsdown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm", "cjs"],
+  dts: true,
+  sourcemap: true,
+  target: "es2022",
+  outDir: "dist",
+  exports: true,
+});

package/vitest.config.mjs

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "./src/__tests__/vitest-environment.mjs",
+    include: ["src/**/__tests__/**/*.test.ts"],
+    reporters: [["default", { summary: false }]],
+  },
+});