agentrail-core 0.0.0 → 0.2.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/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
package/README.md ADDED
@@ -0,0 +1,50 @@
1
+ # agentrail-core
2
+
3
+ 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.
27
+
28
+ ```sh
29
+ npm install agentrail-core
30
+ ```
31
+
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.
42
+
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.
47
+
48
+ ## Licence
49
+
50
+ [Apache-2.0](LICENSE).
@@ -0,0 +1,75 @@
1
+ import type { AgentrailEvent, Component } from './event.js';
2
+ /**
3
+ * Sends a component's events to the collector, `POST <endpoint>/ingest/events`
4
+ * with the source's secret: an edge sends each request's event after the
5
+ * answer, through its platform's `waitUntil`, off the request's path.
6
+ *
7
+ * One call at a time. An event sent while no call is under way goes at once;
8
+ * one sent while a call is under way waits, and goes with every other that
9
+ * waited in the next call, as Kafka's producer batches with no linger: a
10
+ * quiet site sends a call per event, a busy one about a call per round trip
11
+ * to the collector. A call goes from a send still waiting on it: a platform
12
+ * cancels what a request left running once its `waitUntil` has ended, so a
13
+ * call never rides on a request that is done.
14
+ *
15
+ * A call that fails because the network or the collector did (no answer, a
16
+ * 5xx, a 429, or no answer within the try's time) is tried again, after a
17
+ * random part of 250 ms and then of 1 s, so components that failed together
18
+ * do not try again together, and never sooner than a `Retry-After` the
19
+ * collector sent; each try sends the same events, which the collector counts
20
+ * as duplicates once stored. A call ends by its events' deadline: no try or
21
+ * wait starts that would end past it. A call the collector refuses (any other
22
+ * 4xx: a revoked secret, an event it cannot read) is not tried again. Either
23
+ * way the events are given up and the failure goes to `onError`, which logs
24
+ * it unless told otherwise, so a lost collector never fails the platform
25
+ * awaiting a send. Anything else is a fault here, and is thrown.
26
+ */
27
+ export interface CollectorOptions {
28
+ /** The collector's origin, such as `https://api.agentrail.dev`. */
29
+ readonly endpoint: string;
30
+ /** The source's secret, as created for this component. */
31
+ readonly secret: string;
32
+ readonly component: Component;
33
+ /** Events per call; the collector takes calls of up to 16 MB. */
34
+ readonly batchSize?: number;
35
+ /** Tries per call, the first included. */
36
+ readonly attempts?: number;
37
+ /**
38
+ * How long one try may take, its answer read included, before it counts
39
+ * as failed and is tried again; 10 s by default, and never past the
40
+ * call's deadline.
41
+ */
42
+ readonly timeoutMs?: number;
43
+ /** Told of each call whose events were given up. Logs by default. */
44
+ readonly onError?: (error: Error) => void;
45
+ readonly fetch?: typeof fetch;
46
+ readonly sleep?: (ms: number) => Promise<void>;
47
+ }
48
+ export interface Collector {
49
+ /**
50
+ * Sends an event, and resolves once the call carrying it has ended: taken,
51
+ * or given up and told to `onError`. `deadline`, in milliseconds since the
52
+ * epoch, is when that call must end, every try and wait included.
53
+ */
54
+ send(event: AgentrailEvent, deadline: number): Promise<void>;
55
+ }
56
+ /** The collector refused a call: trying again would be refused again. */
57
+ export declare class CollectorRefusedError extends Error {
58
+ readonly status: number;
59
+ readonly name = "CollectorRefusedError";
60
+ constructor(status: number, message: string);
61
+ }
62
+ /** One try failed on the collector's side (a 5xx, a 429): worth another. */
63
+ export declare class CollectorFailedError extends Error {
64
+ readonly status: number;
65
+ readonly name = "CollectorFailedError";
66
+ constructor(status: number, message: string);
67
+ }
68
+ /**
69
+ * No call got through: the network, or the collector, failed every try, or
70
+ * the deadline left no time for another.
71
+ */
72
+ export declare class CollectorUnavailableError extends Error {
73
+ readonly name = "CollectorUnavailableError";
74
+ }
75
+ export declare function createCollector(options: CollectorOptions): Collector;
@@ -0,0 +1,182 @@
1
+ /** The collector refused a call: trying again would be refused again. */
2
+ export class CollectorRefusedError extends Error {
3
+ status;
4
+ name = 'CollectorRefusedError';
5
+ constructor(status, message) {
6
+ super(message);
7
+ this.status = status;
8
+ }
9
+ }
10
+ /** One try failed on the collector's side (a 5xx, a 429): worth another. */
11
+ export class CollectorFailedError extends Error {
12
+ status;
13
+ name = 'CollectorFailedError';
14
+ constructor(status, message) {
15
+ super(message);
16
+ this.status = status;
17
+ }
18
+ }
19
+ /**
20
+ * No call got through: the network, or the collector, failed every try, or
21
+ * the deadline left no time for another.
22
+ */
23
+ export class CollectorUnavailableError extends Error {
24
+ name = 'CollectorUnavailableError';
25
+ }
26
+ /** The longest wait before each try after the first; each wait is a random part of it. */
27
+ const BACKOFF_MS = [250, 1_000];
28
+ function retriable(status) {
29
+ return status === 429 || status >= 500;
30
+ }
31
+ /**
32
+ * How long a `Retry-After` asks to wait, in milliseconds: delay-seconds or an
33
+ * HTTP date (RFC 9110, 10.2.3). Null for none, or for one that is neither: it
34
+ * asks for nothing this client can read.
35
+ */
36
+ function retryAfterMs(value, now) {
37
+ if (value === null)
38
+ return null;
39
+ const text = value.trim();
40
+ if (/^\d+$/u.test(text))
41
+ return Number(text) * 1_000;
42
+ const at = Date.parse(text);
43
+ return Number.isNaN(at) ? null : Math.max(0, at - now);
44
+ }
45
+ /**
46
+ * The try outran its deadline. Fetch rejects with the signal's reason, a
47
+ * `TimeoutError`; a runtime that does not pass the reason on rejects with an
48
+ * `AbortError`, and the deadline's is the only signal a try has.
49
+ */
50
+ function timedOut(error) {
51
+ return (error instanceof DOMException &&
52
+ (error.name === 'TimeoutError' || error.name === 'AbortError'));
53
+ }
54
+ export function createCollector(options) {
55
+ const { endpoint, secret, component, batchSize = 500, attempts = 3, timeoutMs = 10_000, onError = (error) => {
56
+ console.error('agentrail: events were not sent', error);
57
+ }, fetch: send = fetch, sleep = (ms) => new Promise((resolve) => {
58
+ setTimeout(resolve, ms);
59
+ }), } = options;
60
+ const url = new URL('/ingest/events', endpoint);
61
+ const queue = [];
62
+ /** The calls under way; null when none is. */
63
+ let out = null;
64
+ async function deliver(events, deadline) {
65
+ const body = JSON.stringify({
66
+ component: { ...component, surfaces: [...component.surfaces] },
67
+ events,
68
+ });
69
+ let last = null;
70
+ let tries = 0;
71
+ // What the collector last asked a try to wait, at least.
72
+ let asked = null;
73
+ for (let attempt = 0; attempt < attempts; attempt += 1) {
74
+ const longest = BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length) - 1];
75
+ // One call after another: a retry waits out the failure before it.
76
+ const wait = longest === undefined
77
+ ? 0
78
+ : Math.max(Math.random() * longest, asked ?? 0);
79
+ if (Date.now() + wait >= deadline)
80
+ break;
81
+ if (longest !== undefined)
82
+ await sleep(wait);
83
+ const left = deadline - Date.now();
84
+ if (left <= 0)
85
+ break;
86
+ tries += 1;
87
+ let response;
88
+ // What the collector said; a success says nothing more worth reading.
89
+ let answer;
90
+ try {
91
+ // One deadline for the whole try: a collector that sends its headers
92
+ // and never finishes its body holds the try no longer than one that
93
+ // never answers.
94
+ response = await send(url, {
95
+ method: 'POST',
96
+ headers: {
97
+ authorization: `Bearer ${secret}`,
98
+ 'content-type': 'application/json',
99
+ },
100
+ body,
101
+ signal: AbortSignal.timeout(Math.min(timeoutMs, left)),
102
+ });
103
+ answer = response.ok ? null : await response.text();
104
+ }
105
+ catch (error) {
106
+ // Fetch rejects only when the network failed, before or while the
107
+ // answer arrived, or the deadline came first: nothing was read, so
108
+ // the call is tried again.
109
+ if (!(error instanceof TypeError) && !timedOut(error))
110
+ throw error;
111
+ last = error;
112
+ asked = null;
113
+ continue;
114
+ }
115
+ if (answer === null) {
116
+ try {
117
+ await response.body?.cancel();
118
+ }
119
+ catch (error) {
120
+ // The collector took the call: a body whose connection broke after
121
+ // its status changes nothing it said.
122
+ if (!(error instanceof TypeError))
123
+ throw error;
124
+ }
125
+ return;
126
+ }
127
+ if (!retriable(response.status))
128
+ throw new CollectorRefusedError(response.status, `The collector refused ${String(events.length)} events (${String(response.status)}): ${answer}`);
129
+ last = new CollectorFailedError(response.status, `The collector answered ${String(response.status)}: ${answer}`);
130
+ asked = retryAfterMs(response.headers.get('retry-after'), Date.now());
131
+ }
132
+ const outOfTime = tries < attempts;
133
+ throw new CollectorUnavailableError(`${String(events.length)} events were not sent after ${String(tries)} ${tries === 1 ? 'try' : 'tries'}${outOfTime ? ', with no time left before their deadline' : ''}.`, last === null ? undefined : { cause: last });
134
+ }
135
+ /** Sends what was taken off the queue, by the earliest deadline among it. */
136
+ async function sendTaken(taken) {
137
+ const deadline = Math.min(...taken.map((queued) => queued.deadline));
138
+ const events = taken.map((queued) => queued.event);
139
+ const batches = [];
140
+ for (let at = 0; at < events.length; at += batchSize)
141
+ batches.push(events.slice(at, at + batchSize));
142
+ await Promise.all(batches.map(async (batch) => {
143
+ try {
144
+ await deliver(batch, deadline);
145
+ }
146
+ catch (error) {
147
+ // Given up: told to onError, which logs unless told otherwise.
148
+ if (error instanceof CollectorRefusedError ||
149
+ error instanceof CollectorUnavailableError) {
150
+ onError(error);
151
+ return;
152
+ }
153
+ throw error;
154
+ }
155
+ }));
156
+ }
157
+ return {
158
+ async send(event, deadline) {
159
+ const queued = { event, deadline };
160
+ queue.push(queued);
161
+ // The call under way ends first, however it ends: the send that started
162
+ // it reports a fault.
163
+ while (out !== null)
164
+ await Promise.allSettled([out]);
165
+ // Carried by a call that has ended.
166
+ if (!queue.includes(queued))
167
+ return;
168
+ const calls = (async () => {
169
+ try {
170
+ await sendTaken(queue.splice(0, queue.length));
171
+ }
172
+ finally {
173
+ out = null;
174
+ }
175
+ })();
176
+ out = calls;
177
+ // This send waits on the call it started, so the request it belongs to
178
+ // keeps the call alive to its end.
179
+ await calls;
180
+ },
181
+ };
182
+ }
@@ -0,0 +1,154 @@
1
+ /**
2
+ * One event as a component sends it to the collector (`POST /ingest/events`):
3
+ * the journey engine's event less `tenant` and `observedAt`, which the
4
+ * collector stamps from the source's workspace and its own clock, and
5
+ * `hashKeyId`, which it stamps from the key the call names.
6
+ *
7
+ * The engine, private to Argus, holds the schema the collector checks; this
8
+ * package holds the same shape as types, so no component imports the
9
+ * engine. The edge's and the browser's tests check every call they send
10
+ * against the contract Argus writes (`packages/contract`).
11
+ */
12
+ export declare const SURFACES: readonly ["edge", "firewall", "browser", "http", "mcp", "a2a", "genai", "auth", "payment", "custom"];
13
+ export type Surface = (typeof SURFACES)[number];
14
+ /** Whose clock wrote `start` and `end`. */
15
+ export type ClockSource = 'edge' | 'backend' | 'browser' | 'third_party';
16
+ export type SpanKind = 'server' | 'client' | 'internal' | 'producer' | 'consumer';
17
+ /** What a verified principal is. Self-reported identity is never a principal. */
18
+ export type PrincipalKind = 'user' | 'agent_registration' | 'agent_instance' | 'oauth_client' | 'api_key';
19
+ /**
20
+ * What became of a request's Web Bot Auth signature at the component that
21
+ * saw it; only `verified` says who sent the request.
22
+ */
23
+ export type SignatureOutcome = 'verified' | 'invalid' | 'directory_unreachable' | 'unsupported' | 'unchecked';
24
+ export type RegistrationPhase = 'created' | 'claim_completed' | 'expired' | 'revoked';
25
+ export interface SpanContext {
26
+ readonly traceId: string;
27
+ readonly spanId: string;
28
+ }
29
+ export interface AgentrailEvent {
30
+ /** Bumped when a field's meaning changes; stored events are read back. */
31
+ readonly schemaVersion: 1;
32
+ /** Minted here, so a duplicate delivery is the same event. */
33
+ readonly id: string;
34
+ readonly surface: Surface;
35
+ /** What happened, e.g. `http.request`, `tool.call`. */
36
+ readonly kind: string;
37
+ /** This component's clock, milliseconds since the epoch. */
38
+ readonly start: number;
39
+ /** Null for a point event. */
40
+ readonly end: number | null;
41
+ readonly clock: ClockSource;
42
+ /** `argus` for our own components; `other` for anything else. */
43
+ readonly emittedBy: 'argus' | 'other';
44
+ /** OpenTelemetry resource: `service.name` and `service.instance.id`. */
45
+ readonly resource: {
46
+ readonly serviceName: string;
47
+ readonly serviceInstanceId: string | null;
48
+ };
49
+ readonly span: {
50
+ readonly traceId: string;
51
+ readonly spanId: string;
52
+ readonly parentSpanId: string | null;
53
+ readonly kind: SpanKind;
54
+ /** Entered from outside: a parent it names came from whoever called. */
55
+ readonly publicEntry: boolean;
56
+ readonly subtreeSpanIds: string[];
57
+ readonly links: SpanContext[];
58
+ } | null;
59
+ /** `session.id` and `session.previous_id`, set by our edge. */
60
+ readonly session: {
61
+ readonly id: string;
62
+ readonly previousId: string | null;
63
+ } | null;
64
+ readonly http: {
65
+ readonly method: string;
66
+ readonly host: string;
67
+ /** The path with the allowlisted query. */
68
+ readonly path: string;
69
+ readonly status: number | null;
70
+ readonly location: string | null;
71
+ readonly contentType: string | null;
72
+ /** The addresses on the site's own hosts a response named, as requested. */
73
+ readonly linksOut: string[];
74
+ } | null;
75
+ /**
76
+ * Self-reported or network facts: features, never proofs, and what the
77
+ * collector's classifier of who the caller is reads. A component sends
78
+ * each of the later ones where it captured it; the collector fills null
79
+ * where a component sent nothing.
80
+ */
81
+ readonly actor: {
82
+ /** Keyed hash of the client address. */
83
+ readonly egress: string | null;
84
+ readonly userAgent: string | null;
85
+ /** MCP `clientInfo` name, or another client self-description. */
86
+ readonly client: string | null;
87
+ /** The client software's own version: an MCP `clientInfo.version`. */
88
+ readonly clientVersion?: string | null | undefined;
89
+ /** The protocol version the client spoke. */
90
+ readonly protocol?: string | null | undefined;
91
+ /** The `Accept` the request sent. */
92
+ readonly accept?: string | null | undefined;
93
+ /** `Sec-Fetch-Site`, `-Mode` and `-Dest`, which a browser sends and a programmatic fetcher does not. */
94
+ readonly fetchMetadata?: {
95
+ readonly site: string;
96
+ readonly mode: string;
97
+ readonly dest: string;
98
+ } | null | undefined;
99
+ /** What the network said of the client, where the platform tells it: a feature, never a key. */
100
+ readonly network?: {
101
+ readonly asn: number | null;
102
+ readonly country: string | null;
103
+ readonly ja4: string | null;
104
+ } | null | undefined;
105
+ /** A Web Bot Auth signature: the agent URL it named, its key id, and what became of the check. */
106
+ readonly signature?: {
107
+ readonly agent: string;
108
+ readonly keyId: string | null;
109
+ readonly outcome: SignatureOutcome;
110
+ } | null | undefined;
111
+ /** A bot the platform verified against its own directory. */
112
+ readonly verifiedBot?: {
113
+ readonly category: string;
114
+ readonly name: string | null;
115
+ } | null | undefined;
116
+ };
117
+ /** A verified identity, its ids keyed hashes. */
118
+ readonly principal: {
119
+ readonly kind: PrincipalKind;
120
+ readonly id: string;
121
+ readonly actingUserId: string | null;
122
+ } | null;
123
+ readonly registration: {
124
+ readonly id: string;
125
+ readonly phase: RegistrationPhase;
126
+ readonly claimedBy: string | null;
127
+ } | null;
128
+ readonly markers: {
129
+ /** Markers planted in this step's response. */
130
+ readonly served: {
131
+ readonly value: string;
132
+ readonly durable: boolean;
133
+ }[];
134
+ /** Marker strings found in this step's request, as received. */
135
+ readonly seen: string[];
136
+ };
137
+ /** What was hashed or dropped here, and why. */
138
+ readonly redactions: {
139
+ readonly field: string;
140
+ readonly reason: string;
141
+ }[];
142
+ }
143
+ /** The capture code that sent a call, and the surfaces it is set up to capture. */
144
+ export interface Component {
145
+ readonly name: string;
146
+ readonly version: string;
147
+ readonly surfaces: readonly Surface[];
148
+ /**
149
+ * The id of the workspace hash key it hashes with (`hashKeyIdOf`); absent
150
+ * for a component that hashes nothing. The collector refuses an event
151
+ * carrying a hashed value in a call that names no key.
152
+ */
153
+ readonly hashKeyId?: string;
154
+ }