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 +17 -38
- package/dist/event.d.ts +33 -0
- package/dist/index.d.ts +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,50 +1,29 @@
|
|
|
1
1
|
# agentrail-core
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/agentrail-core)
|
|
4
|
+
[](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
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
package/dist/version.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentrail-core",
|
|
3
|
-
"version": "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": {
|