agentrail-core 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,50 +1,29 @@
1
1
  # agentrail-core
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/agentrail-core)](https://www.npmjs.com/package/agentrail-core)
4
+ [![License](https://img.shields.io/github/license/agentrail-co/agentrail-js)](https://github.com/agentrail-co/agentrail-js/blob/main/LICENSE)
5
+
3
6
  What every Agentrail component shares, wherever the Fetch API and WebCrypto
4
- run (Cloudflare Workers, Vercel's edge, Node, browsers): the event the
5
- collector takes, as types; markers, minted and read (`parseMarker`) as the
6
- collector's engine reads them; the keyed hash a workspace hashes addresses
7
- and principals with, and its key's id; W3C trace context; the session
8
- cookie, which ends after 30 minutes idle and a day at most, its id a UUIDv7
9
- that carries its start; and the collector client. Its `send(event,
10
- deadline)` resolves once the call carrying the event has ended: one call is
11
- under way at a time, and what is sent meanwhile goes in the next, together.
12
- It retries what the network or the collector failed after a random wait,
13
- never sooner than a `Retry-After`, ends every call by its deadline, and
14
- tells `onError` of every call given up. And the Web Bot Auth check
15
- (`createSignatureVerifier`): a request's `Signature-Agent`,
16
- `Signature-Input` and `Signature` checked against the keys the named agent
17
- publishes at its `/.well-known/http-message-signatures-directory`, read once
18
- per `max-age` and only from the known signers' hosts (`KNOWN_SIGNERS`) and
19
- the ones a site names, since a caller chooses the URL; Ed25519, RSA-PSS-SHA512 and ECDSA-P256; the outcome is
20
- `verified`, `invalid` (a forged or stale signature, or a key the directory
21
- does not hold), `directory_unreachable` or `unsupported`, so a directory that
22
- is down is never read as a forgery and a signature it does not read is never
23
- called one.
24
-
25
- `agentrail-edge` and `agentrail-browser` are built on it; a component of
26
- your own can be too.
7
+ run: the event the collector takes, markers, the workspace's keyed hash, W3C
8
+ trace context, the session cookie, the signed trace handoff, the Web Bot Auth
9
+ check and the client that sends events to the collector.
10
+
11
+ **To record a site, install one of these instead**:
12
+ [`agentrail-edge`](https://www.npmjs.com/package/agentrail-edge),
13
+ [`agentrail-browser`](https://www.npmjs.com/package/agentrail-browser) or
14
+ [`agentrail-node`](https://www.npmjs.com/package/agentrail-node). They are
15
+ built on this package. Install it directly only to build a component of your
16
+ own:
27
17
 
28
18
  ```sh
29
19
  npm install agentrail-core
30
20
  ```
31
21
 
32
- Before 1.0, a minor version (0.1 to 0.2) may change what the package offers.
33
-
34
- ## Authenticated trace handoff
35
-
36
- `signTraceHandoff(input, hashKey)` and `verifyTraceHandoff(token, expected)`
37
- share a versioned, domain-separated HMAC-SHA256 format. Verification binds the
38
- trace parent, key ID, method and exact origin-form target, and refuses future
39
- or older-than-60-second tokens. `traceHandoffTarget(url)` retains encoded path
40
- and query bytes, including a trailing empty query, and excludes the fragment.
41
- The compatibility contract contains an independently calculated golden token.
22
+ Start from the [repository README](https://github.com/agentrail-co/agentrail-js#readme)
23
+ and the [Journeys guide](https://www.agentrail.co/docs/guides/journeys).
42
24
 
43
- `readTraceHandoff` returns an unverified candidate for synchronous OTel
44
- propagators. Its signature must verify over the returned bytes before its
45
- context becomes trusted. The async verifier performs that check with WebCrypto;
46
- `agentrail-node` performs it synchronously before OTel chooses a parent.
25
+ Before 1.0, a minor version (0.1 to 0.2) may change what the package offers.
47
26
 
48
27
  ## Licence
49
28
 
50
- [Apache-2.0](LICENSE).
29
+ [Apache-2.0](https://github.com/agentrail-co/agentrail-js/blob/main/LICENSE).
package/dist/event.d.ts CHANGED
@@ -26,6 +26,14 @@ export interface SpanContext {
26
26
  readonly traceId: string;
27
27
  readonly spanId: string;
28
28
  }
29
+ /** Approximate network location, resolved before the client address is hashed. */
30
+ export interface IpLocation {
31
+ readonly country: string | null;
32
+ readonly region: string | null;
33
+ readonly city: string | null;
34
+ readonly source: 'dbip' | 'cloudflare' | 'vercel' | 'source';
35
+ readonly observedAt: string;
36
+ }
29
37
  export interface AgentrailEvent {
30
38
  /** Bumped when a field's meaning changes; stored events are read back. */
31
39
  readonly schemaVersion: 1;
@@ -81,6 +89,7 @@ export interface AgentrailEvent {
81
89
  readonly actor: {
82
90
  /** Keyed hash of the client address. */
83
91
  readonly egress: string | null;
92
+ readonly location?: IpLocation | null | undefined;
84
93
  readonly userAgent: string | null;
85
94
  /** MCP `clientInfo` name, or another client self-description. */
86
95
  readonly client: string | null;
@@ -90,6 +99,14 @@ export interface AgentrailEvent {
90
99
  readonly protocol?: string | null | undefined;
91
100
  /** The `Accept` the request sent. */
92
101
  readonly accept?: string | null | undefined;
102
+ /**
103
+ * What the caller's HTTP library wrote: its header names, comma-joined
104
+ * and never a value, and the `Accept-Encoding` it sent (null for none).
105
+ */
106
+ readonly transport?: {
107
+ readonly headerNames: string;
108
+ readonly acceptEncoding: string | null;
109
+ } | null | undefined;
93
110
  /** `Sec-Fetch-Site`, `-Mode` and `-Dest`, which a browser sends and a programmatic fetcher does not. */
94
111
  readonly fetchMetadata?: {
95
112
  readonly site: string;
@@ -134,12 +151,28 @@ export interface AgentrailEvent {
134
151
  /** Marker strings found in this step's request, as received. */
135
152
  readonly seen: string[];
136
153
  };
154
+ /**
155
+ * A WebMCP tool run's facts (kind `agent.tool.executed`): never its
156
+ * arguments or result, only their JSON size.
157
+ */
158
+ readonly webmcp?: WebMcpRun | null | undefined;
137
159
  /** What was hashed or dropped here, and why. */
138
160
  readonly redactions: {
139
161
  readonly field: string;
140
162
  readonly reason: string;
141
163
  }[];
142
164
  }
165
+ /** How a WebMCP tool run ended: `is_error` for a result that said it failed. */
166
+ export type WebMcpOutcome = 'answered' | 'threw' | 'is_error';
167
+ export interface WebMcpRun {
168
+ /** The tool's name; null where it does not match `^[A-Za-z0-9_./-]{1,128}$`. */
169
+ readonly tool: string | null;
170
+ readonly outcome: WebMcpOutcome;
171
+ /** The UTF-8 size of the arguments' JSON; null where they have none. */
172
+ readonly argumentBytes: number | null;
173
+ /** The UTF-8 size of the result's JSON; null where it threw or has none. */
174
+ readonly resultBytes: number | null;
175
+ }
143
176
  /** The capture code that sent a call, and the surfaces it is set up to capture. */
144
177
  export interface Component {
145
178
  readonly name: string;
package/dist/index.d.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  * trace context, the session, and the client that sends events. Nothing
5
5
  * here imports Node, the DOM or OpenTelemetry.
6
6
  */
7
- export { SURFACES, type AgentrailEvent, type ClockSource, type Component, type PrincipalKind, type RegistrationPhase, type SignatureOutcome, type SpanContext, type SpanKind, type Surface, } from './event.js';
7
+ export { SURFACES, type AgentrailEvent, type IpLocation, type ClockSource, type Component, type PrincipalKind, type RegistrationPhase, type SignatureOutcome, type SpanContext, type SpanKind, type Surface, type WebMcpOutcome, type WebMcpRun, } from './event.js';
8
8
  export { MAX_LINK_INDEX, MarkerError, linkMarker, mintMarker, newMarker, parseMarker, type ParsedMarker, } from './marker.js';
9
9
  export { SessionTimeoutError, newSessionId, sessionCookie, sessionStartOf, type SessionCookie, type SessionCookieOptions, } from './session.js';
10
10
  export { hashKeyIdOf, keyedHash } from './hash.js';
package/dist/version.d.ts CHANGED
@@ -4,4 +4,4 @@
4
4
  * own in every call. `test/version.test.ts` holds it to every package's
5
5
  * manifest.
6
6
  */
7
- export declare const VERSION = "0.2.0";
7
+ export declare const VERSION = "0.3.0";
package/dist/version.js CHANGED
@@ -4,4 +4,4 @@
4
4
  * own in every call. `test/version.test.ts` holds it to every package's
5
5
  * manifest.
6
6
  */
7
- export const VERSION = '0.2.0';
7
+ export const VERSION = '0.3.0';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentrail-core",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "What every Agentrail component shares: the event the collector takes, markers, the keyed hash, W3C trace context, and the client that sends events.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {