@copilotkit/learning 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — learning lane
+
+`@copilotkit/learning` versions independently of the monorepo packages
+(`scopes.learning` in `release.config.json`).
+
+`release / create-pr` prepends a section here for each release, and
+`release / publish` reads that section back as the GitHub Release body.
+
+Entries begin with the first independent release cut after this file was added.

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Atai Barkai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @copilotkit/learning
+
+Capture page context, navigation, clicks, form edits, network requests, and developer events as AG-UI `CUSTOM` events. Use the authenticated Core integration to send events to CopilotKit Intelligence.
+
+Capture retains raw URLs, query strings, hashes, page titles, referrers, element text, attributes, and live control values by default. Network events include browser-visible request and response headers and body snapshots. Each body snapshot has a 4 KiB limit and an explicit status for incomplete or unavailable content. Only passwords and credentials are replaced with `[redacted]`, in the browser:
+
+- Values of password fields: `type="password"`, fields that had it earlier in the session (show-password toggles), fields with a credential key as `name`, and `autocomplete` `current-password`, `new-password`, or `one-time-code`.
+- Values typed into password fields, wherever they appear in body snapshots, URLs, or element attributes (the last 20 values of 4 or more characters, kept in memory until stop, also when input capture is off).
+- Values of credential keys such as `password`, `secret`, `api_key`, `access_token`, `authorization`, `cookie`, `jwt`, or `token` in JSON, URL-encoded, and `FormData` bodies, `key: value` text, query strings, hashes, and element attributes, including inside JSON strings nested up to four levels deep. Booleans and `null` stay.
+- Element attributes named like credentials (`data-api-key`, `data-token`).
+- Values of headers whose name is a credential key (`authorization`, `cookie`, `x-api-key`, `x-csrf-token`, …), plus `x-amz-security-token`, `private-token`, and `x-token`.
+- URL user names and passwords (`https://user:pass@host`), which are removed anywhere in captured text.
+
+Redaction runs on the first 16 KiB of a body, before the 4 KiB limit applies. Everything else is captured raw. Binary bodies, hand-built multipart text, XML, single-quoted objects, percent-encoded JSON inside form values, OAuth `code=` values, path tokens, and passwords shorter than 4 characters are not redacted. See [Captured data](https://docs.copilotkit.ai/intelligence/captured-data) for the matching rules and limits.
+
+Use `capture`, `beforeSend`, `ignoreUrls`, and `data-copilotkit-ignore` for your app's exclusions. The deprecated `routes` option no longer masks or transforms paths.
+
+## Authenticated Trajectories
+
+Use Core to connect capture to CopilotKit Intelligence. This experimental integration targets the join and batch APIs in [Intelligence #1569](https://github.com/CopilotKit/Intelligence/pull/1569).
+
+```ts
+import { CopilotKitCore } from "@copilotkit/core";
+
+const copilotkit = new CopilotKitCore({
+  runtimeUrl: "/api/copilotkit",
+  runtimeTransport: "single",
+  learning: {
+    onError: ({ code }) => console.warn("Trajectory capture:", code),
+  },
+});
+
+const result = await copilotkit.startTrajectory();
+if (result.status === "started") {
+  copilotkit.emitTrajectoryEvent("deal.approved", { dealId: "deal-1" });
+}
+
+// Stop on consent withdrawal or when capture is no longer needed.
+copilotkit.stopTrajectory();
+```
+
+An omitted `trajectoryId` generates a UUID. Start succeeds after Runtime authentication and the Phoenix channel join. The Runtime resolves the user on the server and sends only their ID to Intelligence. Browser-supplied identity and container IDs are ignored; container assignment is deferred. Setting `learningContainerIds` for authenticated capture produces a warning. That option applies only to custom sinks.
+
+Capture includes page context, navigation, clicks, form edits, network requests, and developer events. Paths remain unchanged. Thread linking and agent events are deferred for this connection path.
+
+Core sends Phoenix `events` messages with `{ events, dropped }`. It flushes after two seconds, at 50 events, or before the batch exceeds 64 KiB. Each event must fit within 16 KiB, including sequence metadata. Sizes use serialized UTF-8 JSON. The Gateway replies with `{ highestSeq, accepted, rejected }`. This receipt confirms Redis acceptance, not a Postgres commit. Postgres projection follows asynchronously. The receipt does not identify individual rejected events.
+
+Developer events accept any JSON value. Core adds `seq` to object values. It wraps scalars, arrays, `null`, and objects that already contain `seq` as `{ data: value, seq }`, preserving the developer's data.
+
+Sequence numbers increase for the lifetime of a Core instance, including reconnects and stop/start. They start from the Core instance's creation time in microseconds, not 0, so a new Core instance that reuses a Trajectory ID after a page reload continues above the earlier seqs. The Gateway stores each seq once per Trajectory and acknowledges a repeat as accepted, so a new Core instance can still lose events as duplicates if it starts the same ID before the earlier one's seqs run past its own start, roughly when it starts within (seqs used by the earlier instance ÷ 1000) milliseconds. Prefer a new Trajectory UUID for each Core instance when you do not need to continue one.
+
+Capture pauses while disconnected. Reconnect requests fresh credentials. Developer events emitted during recovery count toward `dropped`; their content is not buffered. Core keeps one batch awaiting a receipt and one bounded queue; it does not resend failed batches. Known client losses are reported through `dropped`. Server rejections are already counted by the Gateway. A missing receipt reports `PERSISTENCE_UNKNOWN` through `onError`, because the server may have saved the batch. An `unauthorized` or `trajectory_mismatch` reply stops capture and reconnect attempts.
+
+Stop cancels pending starts and reconnects. It attempts one final queued batch if no receipt is pending, then disconnects without waiting. Stop is not a guarantee that the last batch was saved. A batch still awaiting its receipt reports `PERSISTENCE_UNKNOWN`, including during a normal stop.
+
+In React, pass the same configuration to `CopilotKitProvider`. Set `learning.trajectoryId` to start automatically, or call the Core methods to control capture.
+
+## Custom batch sinks
+
+The original `createCollector` API supports an experimental self-hosted custom batch sink with the same browser capture defaults. It does not authenticate or connect to the Gateway.
+
+```ts
+import { createCollector, httpSink } from "@copilotkit/learning";
+
+const collector = createCollector({
+  sink: httpSink("/api/learning-events"),
+});
+
+collector.start({ trajectoryId: crypto.randomUUID() });
+```
+
+With the custom-sink integration, pass `learning` to `CopilotKitProvider` instead. Core adds Thread context and emits agent and tool events. Agent message text is included in full unless `capture.agentText` is `false`. These additions belong to the custom-sink integration, not standalone browser capture.
+
+Event sequence numbers increase for the lifetime of the collector or Core instance, including across stop/start cycles.
+
+Docs: https://docs.copilotkit.ai/intelligence/capture-interactions