@common-agent/agentdoc 0.0.0-stage → 0.1.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 +202 -0
- package/NOTICE +4 -0
- package/README.md +142 -2
- package/dist/assemble.d.ts +36 -0
- package/dist/assemble.js +918 -0
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +9 -0
- package/dist/check.d.ts +14 -0
- package/dist/check.js +351 -0
- package/dist/cli.d.ts +11 -0
- package/dist/cli.js +368 -0
- package/dist/descriptor.d.ts +21 -0
- package/dist/descriptor.js +102 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +17 -0
- package/dist/paths.d.ts +23 -0
- package/dist/paths.js +58 -0
- package/dist/render.d.ts +21 -0
- package/dist/render.js +368 -0
- package/dist/signatures.d.ts +41 -0
- package/dist/signatures.js +176 -0
- package/dist/types.d.ts +105 -0
- package/dist/types.js +26 -0
- package/dist/util.d.ts +35 -0
- package/dist/util.js +80 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +2 -0
- package/package.json +60 -4
- package/schema/agentdoc-v1.schema.json +199 -0
package/dist/assemble.js
ADDED
|
@@ -0,0 +1,918 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The assembler: one AgentDoc (Common Agent Section 9) from what an agent
|
|
3
|
+
* publishes.
|
|
4
|
+
*
|
|
5
|
+
* Card first. Given only an A2A agent's address, it reads the card at
|
|
6
|
+
* `/.well-known/agent-card.json` (or the older `/.well-known/agent.json`) and
|
|
7
|
+
* writes an honest AgentDoc from it: the card's members restated and cited,
|
|
8
|
+
* and everything the card does not say named in `not_stated`. Where the agent
|
|
9
|
+
* also serves a signed Descriptor (`/.well-known/agent-descriptor.json`), it
|
|
10
|
+
* verifies the `descriptor-statement-v1` signature, cites the Descriptor at
|
|
11
|
+
* its digest, and prefers it over the card wherever both speak (Sections 9.4
|
|
12
|
+
* and 6.8). Signed terms, attestations and evaluation records are used when
|
|
13
|
+
* they are given or the card points to them.
|
|
14
|
+
*
|
|
15
|
+
* It adds no fact (Section 9.3). A member enters only when a listed source
|
|
16
|
+
* says it, every member a source gave enters at `declared` until an
|
|
17
|
+
* evaluation record moves it, a projection that disagrees with its
|
|
18
|
+
* Descriptor is reported on the source rather than merged, and silence is
|
|
19
|
+
* printed by path rather than filled (Section 9.6).
|
|
20
|
+
*
|
|
21
|
+
* `shape.visibility` (Section 9.5.1) is computed from deployment records and
|
|
22
|
+
* from who keeps the agent's door. This assembler reads neither, so it never
|
|
23
|
+
* claims more than it saw: the member is absent and named in `not_stated`.
|
|
24
|
+
*/
|
|
25
|
+
import { canonicalJSON, sha256Digest } from "@common-agent/crypto";
|
|
26
|
+
import { KNOWN_SECTIONS, covered, offeringPaths } from "./paths.js";
|
|
27
|
+
import { checkDescriptorSignature, checkEvalSignature, checkTermsSignature, openAttestation } from "./signatures.js";
|
|
28
|
+
import { ReadError, arr, digestOf, fetchJson, isObj, isUrl, isoSecond, load, str, text, unique } from "./util.js";
|
|
29
|
+
import { VERSION } from "./version.js";
|
|
30
|
+
/** Where an A2A card is served, newest name first. */
|
|
31
|
+
export const CARD_PATHS = ["/.well-known/agent-card.json", "/.well-known/agent.json"];
|
|
32
|
+
/** Where a subject serves its Descriptor (Section 6.7). */
|
|
33
|
+
export const DESCRIPTOR_PATH = "/.well-known/agent-descriptor.json";
|
|
34
|
+
/** Where a subject serves its AgentDoc (Section 9.2). */
|
|
35
|
+
export const AGENTDOC_PATH = "/.well-known/agentdoc.json";
|
|
36
|
+
/** The card extension that commits to signed terms (Agent SoW's a2a-terms). */
|
|
37
|
+
export const TERMS_EXTENSION = "https://agentsow.com/extensions/a2a-terms/v1";
|
|
38
|
+
/** Where a declared interface's machine-readable definition is looked up, by name. */
|
|
39
|
+
export const INTERFACE_REGISTRY = "https://agentroles.ai/interfaces/";
|
|
40
|
+
const ACTS_FOR = ["person", "organization", "anyone"];
|
|
41
|
+
const INTERACTION = ["interactive", "service"];
|
|
42
|
+
const SCOPES = ["task-specific", "open-with-focus", "open-ended"];
|
|
43
|
+
const FOCUSES = ["software", "documents", "data", "research", "operations"];
|
|
44
|
+
const AUTHORITY = ["reads-files", "writes-files", "reads-systems", "updates-systems", "triggers-systems", "runs-commands", "reaches-network", "sends-messages", "spends-money"];
|
|
45
|
+
const CEILINGS = ["job_seconds", "cost_per_job", "spend_per_job", "messages_per_job"];
|
|
46
|
+
const TRIAL_WHO = ["anyone", "signed_in", "verified"];
|
|
47
|
+
const TRIAL_COUNTS = ["per_requester_per_day", "per_day", "per_requester_ever"];
|
|
48
|
+
/** What an open-ended offering never carries: any statement of what it can do (Section 9.5). */
|
|
49
|
+
export const OPEN_ENDED_CLAIMS = ["does", "focus", "role", "can_do", "capabilities", "skills", "examples", "tags"];
|
|
50
|
+
/**
|
|
51
|
+
* A clause quoted from Agent SoW, unchanged. Its `grade` (enforced, evidence or
|
|
52
|
+
* recorded, Agent SoW Section 3) grades the clause, not the agent, so the
|
|
53
|
+
* summary-grade rule allows it, and Agent SoW requires it shown with the clause.
|
|
54
|
+
*/
|
|
55
|
+
function quoteClause(v) {
|
|
56
|
+
if (Array.isArray(v))
|
|
57
|
+
return v.map(quoteClause);
|
|
58
|
+
if (!isObj(v))
|
|
59
|
+
return v;
|
|
60
|
+
const out = {};
|
|
61
|
+
for (const [k, x] of Object.entries(v)) {
|
|
62
|
+
const key = k;
|
|
63
|
+
out[key] = quoteClause(x);
|
|
64
|
+
}
|
|
65
|
+
return out;
|
|
66
|
+
}
|
|
67
|
+
/** Why nothing could be assembled, in plain words. */
|
|
68
|
+
export class AssembleError extends Error {
|
|
69
|
+
constructor(message) {
|
|
70
|
+
super(message);
|
|
71
|
+
this.name = "AssembleError";
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
/** Assemble an AgentDoc. */
|
|
75
|
+
export async function assemble(input) {
|
|
76
|
+
return (await assembleWithNotes(input)).doc;
|
|
77
|
+
}
|
|
78
|
+
// ── a section under construction ────────────────────────────────────────────
|
|
79
|
+
/** A section whose members each remember their source, so a section built from several sources can say which member came from which (Section 9.3). */
|
|
80
|
+
class Section {
|
|
81
|
+
members = {};
|
|
82
|
+
srcOf = {};
|
|
83
|
+
cited = [];
|
|
84
|
+
put(key, value, src) {
|
|
85
|
+
if (value === undefined)
|
|
86
|
+
return;
|
|
87
|
+
this.members[key] = value;
|
|
88
|
+
this.srcOf[key] = src;
|
|
89
|
+
}
|
|
90
|
+
has(key) {
|
|
91
|
+
return key in this.members;
|
|
92
|
+
}
|
|
93
|
+
get(key) {
|
|
94
|
+
return this.members[key];
|
|
95
|
+
}
|
|
96
|
+
/** Cite a source that fills members nested below this level. */
|
|
97
|
+
cite(src) {
|
|
98
|
+
this.cited.push(src);
|
|
99
|
+
}
|
|
100
|
+
build() {
|
|
101
|
+
const keys = Object.keys(this.members);
|
|
102
|
+
if (!keys.length)
|
|
103
|
+
return undefined;
|
|
104
|
+
const from = unique([...keys.map((k) => this.srcOf[k]), ...this.cited]);
|
|
105
|
+
const out = { from, ...this.members };
|
|
106
|
+
if (from.length > 1)
|
|
107
|
+
for (const k of keys)
|
|
108
|
+
out[`${k}_from`] = this.srcOf[k];
|
|
109
|
+
return out;
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
// ── reading a Descriptor (Section 6) ────────────────────────────────────────
|
|
113
|
+
/** One offering's scope members as Section 6.11 reads them. */
|
|
114
|
+
function scopeMembers(o) {
|
|
115
|
+
const focus = typeof o.focus === "string" && FOCUSES.includes(o.focus) ? o.focus : undefined;
|
|
116
|
+
let scope = o.scope === undefined ? "task-specific" : typeof o.scope === "string" && SCOPES.includes(o.scope) ? o.scope : "open-ended";
|
|
117
|
+
if (scope === "open-with-focus" && !focus)
|
|
118
|
+
scope = "open-ended";
|
|
119
|
+
const authority = Array.isArray(o.authority) && o.authority.every((a) => typeof a === "string" && AUTHORITY.includes(a)) ? o.authority : undefined;
|
|
120
|
+
const ceilings = {};
|
|
121
|
+
if (isObj(o.ceilings)) {
|
|
122
|
+
for (const [k, v] of Object.entries(o.ceilings)) {
|
|
123
|
+
if (!CEILINGS.includes(k) || !isObj(v) || v.most === undefined)
|
|
124
|
+
continue;
|
|
125
|
+
ceilings[k] = { most: v.most, ...(v.decided_by === "rule" || v.decided_by === "model" ? { decided_by: v.decided_by } : {}) };
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
return {
|
|
129
|
+
scope,
|
|
130
|
+
...(focus && scope === "open-with-focus" ? { focus } : {}),
|
|
131
|
+
...(text(o.role) ? { role: o.role } : {}),
|
|
132
|
+
...(Array.isArray(o.workspace) ? { workspace: o.workspace.filter(isObj) } : {}),
|
|
133
|
+
...(authority ? { authority } : {}),
|
|
134
|
+
...(o.authority_decided_by === "rule" || o.authority_decided_by === "model" ? { authority_decided_by: o.authority_decided_by } : {}),
|
|
135
|
+
...(Object.keys(ceilings).length ? { ceilings } : {}),
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
/** An offering's trial as Section 7.7 reads it; one that does not validate is no trial (Section 9.6). */
|
|
139
|
+
function trialOf(o) {
|
|
140
|
+
const t = o.trial;
|
|
141
|
+
if (!isObj(t) || !TRIAL_WHO.includes(str(t.who)))
|
|
142
|
+
return { offered: false };
|
|
143
|
+
const l = t.limits;
|
|
144
|
+
if (!isObj(l))
|
|
145
|
+
return { offered: false };
|
|
146
|
+
const whole = (v) => Number.isInteger(v) && v >= 0;
|
|
147
|
+
if (!TRIAL_COUNTS.some((k) => whole(l[k])))
|
|
148
|
+
return { offered: false };
|
|
149
|
+
if (Object.keys(l).some((k) => !TRIAL_COUNTS.includes(k) || !whole(l[k])))
|
|
150
|
+
return { offered: false };
|
|
151
|
+
return { offered: true, who: t.who, ...(isObj(t.shape) ? { shape: t.shape } : {}), limits: l };
|
|
152
|
+
}
|
|
153
|
+
/** An offering's own members, as the Descriptor gives them. */
|
|
154
|
+
function offeringShape(o) {
|
|
155
|
+
const does = text(o.does) ?? text(o.description);
|
|
156
|
+
return {
|
|
157
|
+
...(o.id !== undefined ? { id: o.id } : {}),
|
|
158
|
+
...(o.name !== undefined ? { name: o.name } : {}),
|
|
159
|
+
...(does ? { does } : {}),
|
|
160
|
+
...(Array.isArray(o.inputs) ? { inputs: o.inputs } : {}),
|
|
161
|
+
...(Array.isArray(o.outputs) ? { outputs: o.outputs } : {}),
|
|
162
|
+
...(isObj(o.revisions) ? { revisions: o.revisions } : {}),
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
/** A Descriptor offering as it enters `sells`: an open-ended one carries no statement of what it can do (Section 9.5). */
|
|
166
|
+
function sellsOffering(o) {
|
|
167
|
+
const scope = scopeMembers(o);
|
|
168
|
+
const shape = offeringShape(o);
|
|
169
|
+
const open = scope.scope === "open-ended";
|
|
170
|
+
if (open)
|
|
171
|
+
for (const k of OPEN_ENDED_CLAIMS)
|
|
172
|
+
delete shape[k];
|
|
173
|
+
if (open)
|
|
174
|
+
for (const k of OPEN_ENDED_CLAIMS)
|
|
175
|
+
delete scope[k];
|
|
176
|
+
return {
|
|
177
|
+
...shape,
|
|
178
|
+
...scope,
|
|
179
|
+
...(Array.isArray(o.steps) && o.steps.length ? { steps: o.steps.filter(isObj).map(offeringShape) } : {}),
|
|
180
|
+
trial: trialOf(o),
|
|
181
|
+
state: "declared",
|
|
182
|
+
};
|
|
183
|
+
}
|
|
184
|
+
/** An A2A card skill as it enters `sells`: a projection of an offering, so it is task-specific, which is what an offering without a scope means (Section 6.11). */
|
|
185
|
+
function cardOffering(skill, card) {
|
|
186
|
+
const inModes = Array.isArray(skill.inputModes) ? skill.inputModes : Array.isArray(card.defaultInputModes) ? card.defaultInputModes : undefined;
|
|
187
|
+
const outModes = Array.isArray(skill.outputModes) ? skill.outputModes : Array.isArray(card.defaultOutputModes) ? card.defaultOutputModes : undefined;
|
|
188
|
+
return {
|
|
189
|
+
...(skill.id !== undefined ? { id: skill.id } : {}),
|
|
190
|
+
...(skill.name !== undefined ? { name: skill.name } : {}),
|
|
191
|
+
...(text(skill.description) ? { does: skill.description } : {}),
|
|
192
|
+
scope: "task-specific",
|
|
193
|
+
...(inModes ? { input_modes: inModes } : {}),
|
|
194
|
+
...(outModes ? { output_modes: outModes } : {}),
|
|
195
|
+
...(Array.isArray(skill.tags) && skill.tags.length ? { tags: skill.tags } : {}),
|
|
196
|
+
...(Array.isArray(skill.examples) && skill.examples.length ? { examples: skill.examples } : {}),
|
|
197
|
+
state: "declared",
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
/** The security schemes a card declares, as shapes: what a caller presents, never a binding (Section 9.5, access). */
|
|
201
|
+
function cardSchemes(card) {
|
|
202
|
+
const declared = isObj(card.securitySchemes) ? card.securitySchemes : undefined;
|
|
203
|
+
if (declared) {
|
|
204
|
+
return Object.entries(declared).filter(([, v]) => isObj(v)).map(([id, v]) => {
|
|
205
|
+
const s = v;
|
|
206
|
+
return {
|
|
207
|
+
id,
|
|
208
|
+
...(text(s.type) ? { type: s.type } : {}),
|
|
209
|
+
...(text(s.scheme) ? { scheme: s.scheme } : {}),
|
|
210
|
+
...(text(s.bearerFormat) ? { bearer_format: s.bearerFormat } : {}),
|
|
211
|
+
...(text(s.in) ? { in: s.in } : {}),
|
|
212
|
+
...(text(s.name) ? { name: s.name } : {}),
|
|
213
|
+
...(text(s.description) ? { description: s.description } : {}),
|
|
214
|
+
...(isObj(s.flows) ? { flows: Object.keys(s.flows) } : {}),
|
|
215
|
+
};
|
|
216
|
+
});
|
|
217
|
+
}
|
|
218
|
+
// An explicit empty requirement list says nothing is required; an absent one says nothing at all.
|
|
219
|
+
if (Array.isArray(card.security) && card.security.length === 0)
|
|
220
|
+
return [];
|
|
221
|
+
return undefined;
|
|
222
|
+
}
|
|
223
|
+
function newId(ctx, base) {
|
|
224
|
+
let id = base;
|
|
225
|
+
for (let n = 2; ctx.ids.has(id); n++)
|
|
226
|
+
id = `${base}-${n}`;
|
|
227
|
+
ctx.ids.add(id);
|
|
228
|
+
return id;
|
|
229
|
+
}
|
|
230
|
+
function sourceEntry(id, kind, l, signature, timed) {
|
|
231
|
+
return {
|
|
232
|
+
id,
|
|
233
|
+
kind,
|
|
234
|
+
...(l.url ? { url: l.url } : {}),
|
|
235
|
+
...(timed ? { fetched_at: l.fetchedAt } : {}),
|
|
236
|
+
digest: l.digest,
|
|
237
|
+
signature,
|
|
238
|
+
};
|
|
239
|
+
}
|
|
240
|
+
async function tryLoad(ctx, input, what) {
|
|
241
|
+
try {
|
|
242
|
+
return await load(input, ctx.f, ctx.now, what);
|
|
243
|
+
}
|
|
244
|
+
catch (e) {
|
|
245
|
+
ctx.notes.push(`The ${what} could not be read: ${e.message}.`);
|
|
246
|
+
return null;
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
/** The address as a URL, with https assumed where no scheme is given. */
|
|
250
|
+
function addressUrl(address) {
|
|
251
|
+
const a = address.trim();
|
|
252
|
+
try {
|
|
253
|
+
return new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(a) ? a : `https://${a}`);
|
|
254
|
+
}
|
|
255
|
+
catch {
|
|
256
|
+
throw new AssembleError(`${address} is not an address this tool can read. Give the agent's address, such as https://your-agent.example`);
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
/** The places a card may be, for an address: the address itself when it names a JSON file, else the well-known paths under it and under its origin. */
|
|
260
|
+
export function cardCandidates(address) {
|
|
261
|
+
const u = addressUrl(address);
|
|
262
|
+
if (/\.json$/i.test(u.pathname))
|
|
263
|
+
return [u.href];
|
|
264
|
+
const path = u.pathname.replace(/\/+$/, "");
|
|
265
|
+
return unique([...(path ? CARD_PATHS.map((p) => `${u.origin}${path}${p}`) : []), ...CARD_PATHS.map((p) => `${u.origin}${p}`)]);
|
|
266
|
+
}
|
|
267
|
+
/** The base a card was found under: the URL with its well-known suffix taken off. */
|
|
268
|
+
function baseOf(cardUrl) {
|
|
269
|
+
for (const p of CARD_PATHS)
|
|
270
|
+
if (cardUrl.endsWith(p))
|
|
271
|
+
return cardUrl.slice(0, -p.length);
|
|
272
|
+
return new URL(cardUrl).origin;
|
|
273
|
+
}
|
|
274
|
+
async function discoverCard(ctx, address) {
|
|
275
|
+
const tried = [];
|
|
276
|
+
for (const url of cardCandidates(address)) {
|
|
277
|
+
tried.push(url);
|
|
278
|
+
try {
|
|
279
|
+
const l = await fetchJson(ctx.f, url, ctx.now);
|
|
280
|
+
if (isObj(l.value))
|
|
281
|
+
return l;
|
|
282
|
+
ctx.notes.push(`${url} is not a JSON object, so it is not an agent card.`);
|
|
283
|
+
}
|
|
284
|
+
catch (e) {
|
|
285
|
+
if (!(e instanceof ReadError && e.status === 404))
|
|
286
|
+
ctx.notes.push(`${e.message}.`);
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
ctx.notes.push(`No A2A Agent Card was found. Tried ${tried.join(" and ")}.`);
|
|
290
|
+
return null;
|
|
291
|
+
}
|
|
292
|
+
async function discoverDescriptor(ctx, bases) {
|
|
293
|
+
for (const base of unique(bases)) {
|
|
294
|
+
const url = `${base}${DESCRIPTOR_PATH}`;
|
|
295
|
+
try {
|
|
296
|
+
return await fetchJson(ctx.f, url, ctx.now);
|
|
297
|
+
}
|
|
298
|
+
catch (e) {
|
|
299
|
+
if (!(e instanceof ReadError && e.status === 404))
|
|
300
|
+
ctx.notes.push(`${e.message}.`);
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
return null;
|
|
304
|
+
}
|
|
305
|
+
// ── assembling ──────────────────────────────────────────────────────────────
|
|
306
|
+
/** Assemble an AgentDoc, with plain notes on what the assembler found on the way. */
|
|
307
|
+
export async function assembleWithNotes(input) {
|
|
308
|
+
const f = input.fetch ?? globalThis.fetch;
|
|
309
|
+
const ctx = { f, now: isoSecond(input.now ?? new Date()), notes: [], sources: [], ids: new Set() };
|
|
310
|
+
if (input.package !== undefined)
|
|
311
|
+
return assemblePackage(input, ctx);
|
|
312
|
+
// The card: handed in, or discovered at the address.
|
|
313
|
+
let card = null;
|
|
314
|
+
if (input.card !== undefined)
|
|
315
|
+
card = await tryLoad(ctx, input.card, "agent card");
|
|
316
|
+
else if (input.address)
|
|
317
|
+
card = await discoverCard(ctx, input.address);
|
|
318
|
+
if (card && !isObj(card.value)) {
|
|
319
|
+
ctx.notes.push("The agent card is not a JSON object, so it was not used.");
|
|
320
|
+
card = null;
|
|
321
|
+
}
|
|
322
|
+
// The Descriptor: handed in, or discovered beside the card.
|
|
323
|
+
let desc = null;
|
|
324
|
+
if (input.descriptor !== undefined)
|
|
325
|
+
desc = await tryLoad(ctx, input.descriptor, "Descriptor");
|
|
326
|
+
else {
|
|
327
|
+
const bases = [];
|
|
328
|
+
if (card?.url)
|
|
329
|
+
bases.push(baseOf(card.url));
|
|
330
|
+
if (input.address)
|
|
331
|
+
bases.push(addressUrl(input.address).origin);
|
|
332
|
+
if (bases.length)
|
|
333
|
+
desc = await discoverDescriptor(ctx, bases);
|
|
334
|
+
}
|
|
335
|
+
if (!card && !desc) {
|
|
336
|
+
throw new AssembleError(input.address
|
|
337
|
+
? `Nothing to assemble from: ${input.address} serves no A2A Agent Card and no Descriptor. ${ctx.notes.join(" ")}`.trim()
|
|
338
|
+
: "Nothing to assemble from. Give an agent's address, its card or its Descriptor.");
|
|
339
|
+
}
|
|
340
|
+
const c = card && isObj(card.value) ? card.value : {};
|
|
341
|
+
const cardId = card ? newId(ctx, "card") : "";
|
|
342
|
+
if (card) {
|
|
343
|
+
const signed = Array.isArray(c.signatures) && c.signatures.length > 0;
|
|
344
|
+
ctx.sources.push(sourceEntry(cardId, "a2a-card", card, signed ? "not_checked" : "unsigned", true));
|
|
345
|
+
}
|
|
346
|
+
// The Descriptor is used only when it is one and its signature does not fail.
|
|
347
|
+
let d = null;
|
|
348
|
+
let descId = "";
|
|
349
|
+
if (desc) {
|
|
350
|
+
descId = newId(ctx, "descriptor");
|
|
351
|
+
const v = desc.value;
|
|
352
|
+
const sig = checkDescriptorSignature(v);
|
|
353
|
+
const entry = sourceEntry(descId, "agent-descriptor", desc, sig.state, true);
|
|
354
|
+
if (isObj(v) && v.agent_version !== undefined)
|
|
355
|
+
entry.agent_version = String(v.agent_version);
|
|
356
|
+
if (!isObj(v) || v.format !== "agent-descriptor-v1") {
|
|
357
|
+
entry.not_used = "it is not an agent-descriptor-v1 document";
|
|
358
|
+
ctx.notes.push("The Descriptor is not an agent-descriptor-v1 document, so it was not used.");
|
|
359
|
+
}
|
|
360
|
+
else if (sig.state === "failed") {
|
|
361
|
+
entry.not_used = `its signature does not verify (${sig.note ?? "failed"})`;
|
|
362
|
+
ctx.notes.push(`The Descriptor's signature does not verify: ${sig.note ?? "it failed"}. Nothing in it was used. Sign it again with common-agent-doc sign.`);
|
|
363
|
+
}
|
|
364
|
+
else {
|
|
365
|
+
d = v;
|
|
366
|
+
if (sig.state === "unsigned")
|
|
367
|
+
ctx.notes.push("The Descriptor is not signed. Readers take it only as far as the place it was fetched from. Sign it with common-agent-doc sign.");
|
|
368
|
+
if (sig.state === "not_checked")
|
|
369
|
+
ctx.notes.push(`The Descriptor's signature was not checked: ${sig.note}.`);
|
|
370
|
+
}
|
|
371
|
+
ctx.sources.push(entry);
|
|
372
|
+
}
|
|
373
|
+
// A card is a projection of the Descriptor (Section 6.8): a disagreement is reported on the card, never merged.
|
|
374
|
+
if (card && d) {
|
|
375
|
+
const dis = [];
|
|
376
|
+
if (text(c.description) && text(d.does) && text(c.description) !== text(d.does))
|
|
377
|
+
dis.push(`the card's description differs from the Descriptor's does`);
|
|
378
|
+
if (text(c.version) && d.agent_version !== undefined && text(c.version) !== String(d.agent_version))
|
|
379
|
+
dis.push(`the card's version "${c.version}" differs from the Descriptor's agent_version "${String(d.agent_version)}"`);
|
|
380
|
+
const offered = new Set(arr(d.offerings).filter(isObj).map((o) => str(o.id)));
|
|
381
|
+
const skills = arr(c.skills).filter(isObj).map((s) => str(s.id)).filter(Boolean);
|
|
382
|
+
const extra = skills.filter((s) => !offered.has(s));
|
|
383
|
+
if (extra.length)
|
|
384
|
+
dis.push(`the card lists skill${extra.length === 1 ? "" : "s"} ${extra.join(", ")} that the Descriptor does not offer`);
|
|
385
|
+
const missing = [...offered].filter((o) => o && !skills.includes(o));
|
|
386
|
+
if (skills.length && missing.length)
|
|
387
|
+
dis.push(`the Descriptor offers ${missing.join(", ")}, which the card does not list`);
|
|
388
|
+
if (dis.length) {
|
|
389
|
+
ctx.sources.find((s) => s.id === cardId).disagreements = dis;
|
|
390
|
+
for (const x of dis)
|
|
391
|
+
ctx.notes.push(`Disagreement: ${x}. The Descriptor's value is used.`);
|
|
392
|
+
}
|
|
393
|
+
}
|
|
394
|
+
const sections = {};
|
|
395
|
+
const offerings = buildSells(ctx, c, cardId, d, descId);
|
|
396
|
+
const usedTerms = await readTerms(ctx, input, c, cardId);
|
|
397
|
+
// identity
|
|
398
|
+
const identity = new Section();
|
|
399
|
+
if (card) {
|
|
400
|
+
identity.put("name", text(c.name), cardId);
|
|
401
|
+
if (!d)
|
|
402
|
+
identity.put("description", text(c.description), cardId);
|
|
403
|
+
const provider = isObj(c.provider) ? c.provider : {};
|
|
404
|
+
identity.put("operator", text(provider.organization), cardId);
|
|
405
|
+
identity.put("url", text(provider.url), cardId);
|
|
406
|
+
if (!d)
|
|
407
|
+
identity.put("version", text(c.version), cardId);
|
|
408
|
+
identity.put("documentation", text(c.documentationUrl), cardId);
|
|
409
|
+
}
|
|
410
|
+
if (d) {
|
|
411
|
+
identity.put("description", text(d.does), descId);
|
|
412
|
+
if (d.agent_version !== undefined)
|
|
413
|
+
identity.put("version", String(d.agent_version), descId);
|
|
414
|
+
const subj = isObj(d.subject) ? d.subject : {};
|
|
415
|
+
identity.put("handle", text(subj.handle), descId);
|
|
416
|
+
if (typeof d.acts_for === "string" && ACTS_FOR.includes(d.acts_for)) {
|
|
417
|
+
identity.put("acts_for", d.acts_for, descId);
|
|
418
|
+
if (d.acts_for === "organization")
|
|
419
|
+
identity.put("organization_name", text(d.organization_name), descId);
|
|
420
|
+
}
|
|
421
|
+
if (typeof d.fleet === "boolean")
|
|
422
|
+
identity.put("fleet", d.fleet, descId);
|
|
423
|
+
}
|
|
424
|
+
setSection(sections, "identity", identity);
|
|
425
|
+
// shape: whether a person attends it. visibility is never computed here (see the head of this file).
|
|
426
|
+
if (d && typeof d.interaction === "string" && INTERACTION.includes(d.interaction)) {
|
|
427
|
+
const shape = new Section();
|
|
428
|
+
shape.put("interaction", d.interaction, descId);
|
|
429
|
+
setSection(sections, "shape", shape);
|
|
430
|
+
}
|
|
431
|
+
if (d)
|
|
432
|
+
descriptorSections(sections, d, descId);
|
|
433
|
+
// asked: each declared interface, with the exchanges its published definition lists.
|
|
434
|
+
if (d && arr(d.interfaces).length)
|
|
435
|
+
sections.asked = await askedSection(ctx, d, descId, true);
|
|
436
|
+
// sells
|
|
437
|
+
if (offerings.list.length) {
|
|
438
|
+
const sells = new Section();
|
|
439
|
+
sells.put("scopes", unique(offerings.list.map((o) => str(o.scope))), offerings.src);
|
|
440
|
+
sells.put("offerings", offerings.list, offerings.src);
|
|
441
|
+
if (d && text(d.samples_ref))
|
|
442
|
+
sells.put("samples_ref", d.samples_ref, descId);
|
|
443
|
+
for (const t of usedTerms) {
|
|
444
|
+
let priced = false;
|
|
445
|
+
for (const o of offerings.list) {
|
|
446
|
+
if (!t.offerings.has(str(o.id)) || o.price !== undefined)
|
|
447
|
+
continue;
|
|
448
|
+
const price = isObj(t.value.price) ? quoteClause(t.value.price) : undefined;
|
|
449
|
+
if (!price)
|
|
450
|
+
continue;
|
|
451
|
+
o.price = price;
|
|
452
|
+
o.price_from = t.id;
|
|
453
|
+
if (typeof price.arrangement === "string") {
|
|
454
|
+
o.arrangement = price.arrangement;
|
|
455
|
+
o.arrangement_from = t.id;
|
|
456
|
+
}
|
|
457
|
+
priced = true;
|
|
458
|
+
}
|
|
459
|
+
if (priced)
|
|
460
|
+
sells.cite(t.id);
|
|
461
|
+
}
|
|
462
|
+
setSection(sections, "sells", sells);
|
|
463
|
+
}
|
|
464
|
+
// access: where a message is sent and what a caller presents, from the card; the per-caller limits, from the Descriptor.
|
|
465
|
+
const access = new Section();
|
|
466
|
+
if (card) {
|
|
467
|
+
access.put("address", text(c.url), cardId);
|
|
468
|
+
if (text(c.url))
|
|
469
|
+
access.put("protocol", "a2a", cardId);
|
|
470
|
+
access.put("transport", text(c.preferredTransport), cardId);
|
|
471
|
+
access.put("protocol_version", text(c.protocolVersion), cardId);
|
|
472
|
+
access.put("schemes", cardSchemes(c), cardId);
|
|
473
|
+
const caps = isObj(c.capabilities) ? c.capabilities : {};
|
|
474
|
+
const capabilities = {};
|
|
475
|
+
if (typeof caps.streaming === "boolean")
|
|
476
|
+
capabilities.streaming = caps.streaming;
|
|
477
|
+
if (typeof caps.pushNotifications === "boolean")
|
|
478
|
+
capabilities.push_notifications = caps.pushNotifications;
|
|
479
|
+
if (Object.keys(capabilities).length)
|
|
480
|
+
access.put("capabilities", capabilities, cardId);
|
|
481
|
+
}
|
|
482
|
+
if (d && isObj(d.limits))
|
|
483
|
+
access.put("limits", d.limits, descId);
|
|
484
|
+
setSection(sections, "access", access);
|
|
485
|
+
// handling: where it runs, from the Descriptor; where content is processed and how long it is kept, from signed terms.
|
|
486
|
+
const handling = new Section();
|
|
487
|
+
if (d && arr(d.hosted_in).length)
|
|
488
|
+
handling.put("hosted_in", d.hosted_in, descId);
|
|
489
|
+
const conf = usedTerms.find((t) => isObj(t.value.confidentiality));
|
|
490
|
+
if (conf) {
|
|
491
|
+
const k = conf.value.confidentiality;
|
|
492
|
+
if (Array.isArray(k.processed_in))
|
|
493
|
+
handling.put("processed_in", k.processed_in, conf.id);
|
|
494
|
+
if (isObj(k.retention) && typeof k.retention.max_days === "number")
|
|
495
|
+
handling.put("retention_max_days", k.retention.max_days, conf.id);
|
|
496
|
+
if (Array.isArray(k.processors))
|
|
497
|
+
handling.put("processors", quoteClause(k.processors), conf.id);
|
|
498
|
+
if (isObj(k.promises))
|
|
499
|
+
handling.put("promises", quoteClause(k.promises), conf.id);
|
|
500
|
+
}
|
|
501
|
+
setSection(sections, "handling", handling);
|
|
502
|
+
const subjectId = d && isObj(d.subject) && text(d.subject.id) ? String(d.subject.id) : undefined;
|
|
503
|
+
applyEvalRecords(ctx, sections, input.evalRecords ?? [], subjectId);
|
|
504
|
+
applyAttestations(ctx, sections, input.attestations ?? []);
|
|
505
|
+
// The subject: its key where a Descriptor binds one, else the card's address, which is the most stable name the card gives.
|
|
506
|
+
const subject = {
|
|
507
|
+
id: subjectId ?? text(c.url) ?? (card?.url ? new URL(card.url).origin : undefined) ?? (input.address ? addressUrl(input.address).origin : undefined) ?? (card ?? desc).digest,
|
|
508
|
+
...(d && isObj(d.subject) && text(d.subject.handle) ? { handle: String(d.subject.handle) } : {}),
|
|
509
|
+
...(text(c.name) ? { name: String(c.name) } : {}),
|
|
510
|
+
};
|
|
511
|
+
const doc = {
|
|
512
|
+
agentdoc: "v1",
|
|
513
|
+
subject,
|
|
514
|
+
assembled_at: ctx.now,
|
|
515
|
+
assembled_by: input.assembledBy ?? `@common-agent/agentdoc ${VERSION}; the assembly is not signed`,
|
|
516
|
+
sources: ctx.sources,
|
|
517
|
+
sections,
|
|
518
|
+
not_stated: notStatedOf(sections, { pkg: false, card: !!card }),
|
|
519
|
+
signatures: [],
|
|
520
|
+
};
|
|
521
|
+
return { doc, notes: ctx.notes };
|
|
522
|
+
}
|
|
523
|
+
function setSection(sections, name, s) {
|
|
524
|
+
const built = s.build();
|
|
525
|
+
if (built)
|
|
526
|
+
sections[name] = built;
|
|
527
|
+
}
|
|
528
|
+
/** The offerings, from the Descriptor where there is one, else from the card's skills. */
|
|
529
|
+
function buildSells(ctx, c, cardId, d, descId) {
|
|
530
|
+
if (d)
|
|
531
|
+
return { list: arr(d.offerings).filter(isObj).map(sellsOffering), src: descId };
|
|
532
|
+
if (cardId)
|
|
533
|
+
return { list: arr(c.skills).filter(isObj).map((s) => cardOffering(s, c)), src: cardId };
|
|
534
|
+
void ctx;
|
|
535
|
+
return { list: [], src: "" };
|
|
536
|
+
}
|
|
537
|
+
/** The sections only a Descriptor fills: role, refuses, reaches, leaves and configs. */
|
|
538
|
+
function descriptorSections(sections, d, descId) {
|
|
539
|
+
if (text(d.role)) {
|
|
540
|
+
const role = new Section();
|
|
541
|
+
role.put("name", d.role, descId);
|
|
542
|
+
role.put("declared_in", "descriptor", descId);
|
|
543
|
+
role.put("state", "declared", descId);
|
|
544
|
+
setSection(sections, "role", role);
|
|
545
|
+
}
|
|
546
|
+
// What it refuses and what it hands to a person: both the operator's own sentences, carried as prose.
|
|
547
|
+
const refusals = typeof d.refusals === "string" ? text(d.refusals) : Array.isArray(d.refusals) ? d.refusals.filter((x) => typeof x === "string" && x.trim()).join("\n") || undefined : undefined;
|
|
548
|
+
const handsOver = arr(d.escalates).filter((x) => typeof x === "string" && x.trim().length > 0);
|
|
549
|
+
const refuses = new Section();
|
|
550
|
+
if (refusals) {
|
|
551
|
+
refuses.put("statement", refusals, descId);
|
|
552
|
+
refuses.put("kind", "prose", descId);
|
|
553
|
+
}
|
|
554
|
+
if (handsOver.length)
|
|
555
|
+
refuses.put("hands_over", handsOver, descId);
|
|
556
|
+
setSection(sections, "refuses", refuses);
|
|
557
|
+
// reaches: the standing systems, `role` read as the alias of `name` (Section 6.2).
|
|
558
|
+
const systems = arr(d.systems).filter(isObj).map((s) => {
|
|
559
|
+
const { role, name, ...rest } = s;
|
|
560
|
+
const n = name ?? role;
|
|
561
|
+
return { ...(n !== undefined ? { name: n } : {}), ...rest };
|
|
562
|
+
});
|
|
563
|
+
const ceilings = arr(d.ceilings).filter((x) => isObj(x) && typeof x.system === "string");
|
|
564
|
+
const reaches = new Section();
|
|
565
|
+
if (systems.length)
|
|
566
|
+
reaches.put("systems", systems, descId);
|
|
567
|
+
if (ceilings.length)
|
|
568
|
+
reaches.put("ceilings", ceilings, descId);
|
|
569
|
+
setSection(sections, "reaches", reaches);
|
|
570
|
+
const records = arr(d.records).filter((r) => isObj(r) && typeof r.name === "string");
|
|
571
|
+
if (records.length) {
|
|
572
|
+
const leaves = new Section();
|
|
573
|
+
leaves.put("records", records, descId);
|
|
574
|
+
setSection(sections, "leaves", leaves);
|
|
575
|
+
}
|
|
576
|
+
// configs: an agent whose Descriptor has no run_config takes no settings (Section 6.2), which is a statement, not silence.
|
|
577
|
+
const configs = new Section();
|
|
578
|
+
const rc = isObj(d.run_config) ? d.run_config : undefined;
|
|
579
|
+
configs.put("settings", rc && Array.isArray(rc.settings) ? rc.settings.filter(isObj) : [], descId);
|
|
580
|
+
if (rc && Array.isArray(rc.tested_models))
|
|
581
|
+
configs.put("tested_models", rc.tested_models, descId);
|
|
582
|
+
if (rc && Array.isArray(rc.named))
|
|
583
|
+
configs.put("named", rc.named.filter(isObj).map((n) => ({ ...(n.name !== undefined ? { name: n.name } : {}), ...(n.digest !== undefined ? { digest: n.digest } : {}) })), descId);
|
|
584
|
+
if (rc && typeof rc.replay === "boolean")
|
|
585
|
+
configs.put("replay", rc.replay, descId);
|
|
586
|
+
setSection(sections, "configs", configs);
|
|
587
|
+
}
|
|
588
|
+
/** The `asked` section: every declared interface, each with the exchanges its definition publishes, each at `declared`. */
|
|
589
|
+
async function askedSection(ctx, d, descId, resolve) {
|
|
590
|
+
const from = [descId];
|
|
591
|
+
const interfaces = [];
|
|
592
|
+
for (const name of arr(d.interfaces).filter((x) => typeof x === "string" && x.trim().length > 0)) {
|
|
593
|
+
let def = null;
|
|
594
|
+
if (resolve) {
|
|
595
|
+
const url = isUrl(name) ? name : `${INTERFACE_REGISTRY}${encodeURIComponent(name)}.json`;
|
|
596
|
+
try {
|
|
597
|
+
def = await fetchJson(ctx.f, url, ctx.now);
|
|
598
|
+
}
|
|
599
|
+
catch {
|
|
600
|
+
def = null;
|
|
601
|
+
}
|
|
602
|
+
}
|
|
603
|
+
const v = def && isObj(def.value) ? def.value : null;
|
|
604
|
+
const exchanges = v ? arr(v.exchanges).filter(isObj) : [];
|
|
605
|
+
if (def && exchanges.length) {
|
|
606
|
+
const id = newId(ctx, `iface-${name.replace(/[^A-Za-z0-9_-]+/g, "-")}`);
|
|
607
|
+
ctx.sources.push(sourceEntry(id, "interface-definition", def, Array.isArray(v.signatures) && v.signatures.length ? "not_checked" : "unsigned", true));
|
|
608
|
+
from.push(id);
|
|
609
|
+
interfaces.push({
|
|
610
|
+
name,
|
|
611
|
+
...(text(v.version) ? { version: v.version } : {}),
|
|
612
|
+
...(text(v.definition) ? { definition: v.definition } : {}),
|
|
613
|
+
declared_in: descId,
|
|
614
|
+
definition_from: id,
|
|
615
|
+
exchanges: exchanges.map((e) => ({
|
|
616
|
+
...(e.id !== undefined ? { id: e.id } : {}),
|
|
617
|
+
...(e.asks !== undefined ? { asks: e.asks } : {}),
|
|
618
|
+
...(Array.isArray(e.answer_carries) ? { answer_carries: e.answer_carries } : {}),
|
|
619
|
+
state: "declared",
|
|
620
|
+
})),
|
|
621
|
+
});
|
|
622
|
+
}
|
|
623
|
+
else {
|
|
624
|
+
if (resolve)
|
|
625
|
+
ctx.notes.push(`The definition of the interface ${name} could not be read, so its exchanges are not listed.`);
|
|
626
|
+
interfaces.push({ name, declared_in: descId });
|
|
627
|
+
}
|
|
628
|
+
}
|
|
629
|
+
return { from, interfaces };
|
|
630
|
+
}
|
|
631
|
+
/** Read signed terms: those handed in, and those the card's terms extension commits to. Only a verified proposal is used (Agent SoW a2a-terms, Section 7). */
|
|
632
|
+
async function readTerms(ctx, input, c, cardId) {
|
|
633
|
+
const wanted = [];
|
|
634
|
+
for (const t of input.terms ?? [])
|
|
635
|
+
wanted.push({ input: t });
|
|
636
|
+
if (cardId && isObj(c.capabilities)) {
|
|
637
|
+
for (const ext of arr(c.capabilities.extensions).filter(isObj)) {
|
|
638
|
+
if (ext.uri !== TERMS_EXTENSION || !isObj(ext.params))
|
|
639
|
+
continue;
|
|
640
|
+
for (const p of arr(ext.params.proposals).filter(isObj)) {
|
|
641
|
+
if (!text(p.url) || !isUrl(str(p.url)))
|
|
642
|
+
continue;
|
|
643
|
+
if (wanted.some((w) => w.input === p.url))
|
|
644
|
+
continue;
|
|
645
|
+
wanted.push({ input: str(p.url), committed: text(p.digest), offering: text(p.offering), via: cardId });
|
|
646
|
+
}
|
|
647
|
+
}
|
|
648
|
+
}
|
|
649
|
+
const used = [];
|
|
650
|
+
for (const w of wanted) {
|
|
651
|
+
const l = await tryLoad(ctx, w.input, "terms");
|
|
652
|
+
if (!l)
|
|
653
|
+
continue;
|
|
654
|
+
const id = newId(ctx, "terms");
|
|
655
|
+
const sig = checkTermsSignature(l.value);
|
|
656
|
+
const entry = sourceEntry(id, "sow-standing-proposal", l, sig.state, true);
|
|
657
|
+
let why;
|
|
658
|
+
if (!isObj(l.value))
|
|
659
|
+
why = "it is not a JSON object";
|
|
660
|
+
else if (w.committed && w.committed !== sha256Digest(canonicalJSON(l.value)) && w.committed !== l.digest)
|
|
661
|
+
why = "its digest is not the one the card commits to";
|
|
662
|
+
else if (sig.state !== "verified")
|
|
663
|
+
why = sig.state === "unsigned" ? "it carries no provider signature, so it is a suggestion, not terms" : `its provider signature does not verify (${sig.note ?? sig.state})`;
|
|
664
|
+
if (w.via)
|
|
665
|
+
entry.committed_by = w.via;
|
|
666
|
+
if (why) {
|
|
667
|
+
entry.not_used = why;
|
|
668
|
+
ctx.notes.push(`Terms at ${l.url ?? "the given file"} were not used: ${why}.`);
|
|
669
|
+
}
|
|
670
|
+
else {
|
|
671
|
+
const v = l.value;
|
|
672
|
+
const scope = isObj(v.scope) ? v.scope : {};
|
|
673
|
+
const offerings = new Set(arr(scope.offerings).filter((x) => typeof x === "string"));
|
|
674
|
+
if (w.offering)
|
|
675
|
+
offerings.add(w.offering);
|
|
676
|
+
used.push({ id, value: v, offerings });
|
|
677
|
+
}
|
|
678
|
+
ctx.sources.push(entry);
|
|
679
|
+
}
|
|
680
|
+
return used;
|
|
681
|
+
}
|
|
682
|
+
/** Evaluation records (Section 8.4): listed like any source, and applied case by case, never wholesale, only when verified and about this subject. */
|
|
683
|
+
function applyEvalRecords(ctx, sections, records, subjectId) {
|
|
684
|
+
const standing = sections.standing ?? { from: [] };
|
|
685
|
+
const entries = arr(standing.entries);
|
|
686
|
+
for (const rec of records) {
|
|
687
|
+
const id = newId(ctx, "eval");
|
|
688
|
+
const sig = checkEvalSignature(rec);
|
|
689
|
+
const r = isObj(rec) ? rec : {};
|
|
690
|
+
ctx.sources.push({ id, kind: "eval-record", fetched_at: ctx.now, digest: digestOf(rec), signature: sig.state });
|
|
691
|
+
entries.push({
|
|
692
|
+
kind: "eval-record",
|
|
693
|
+
...(text(r.by) ?? sig.by ? { by: text(r.by) ?? sig.by } : {}),
|
|
694
|
+
...(text(r.produced_at) ? { as_of: r.produced_at } : {}),
|
|
695
|
+
...(typeof r.conforms === "boolean" ? { conforms: r.conforms } : {}),
|
|
696
|
+
signature: sig.state,
|
|
697
|
+
record: id,
|
|
698
|
+
});
|
|
699
|
+
standing.from = unique([...standing.from, id]);
|
|
700
|
+
const about = isObj(r.subject) ? r.subject.agent_key : undefined;
|
|
701
|
+
if (sig.state !== "verified" || !subjectId || about !== subjectId) {
|
|
702
|
+
if (sig.state === "verified" && about !== subjectId)
|
|
703
|
+
ctx.notes.push("An evaluation record names another subject, so it moved nothing.");
|
|
704
|
+
continue;
|
|
705
|
+
}
|
|
706
|
+
const at = text(r.produced_at);
|
|
707
|
+
const move = (target, verdict) => {
|
|
708
|
+
if (verdict === "pass") {
|
|
709
|
+
target.state = "confirmed";
|
|
710
|
+
if (at)
|
|
711
|
+
target.confirmed_at = at;
|
|
712
|
+
target.confirmed_by = id;
|
|
713
|
+
return true;
|
|
714
|
+
}
|
|
715
|
+
if (verdict === "fail") {
|
|
716
|
+
target.state = "failed";
|
|
717
|
+
if (at)
|
|
718
|
+
target.failed_at = at;
|
|
719
|
+
target.failed_by = id;
|
|
720
|
+
return true;
|
|
721
|
+
}
|
|
722
|
+
return false;
|
|
723
|
+
};
|
|
724
|
+
const asked = sections.asked;
|
|
725
|
+
const sells = sections.sells;
|
|
726
|
+
for (const cs of arr(r.cases).filter(isObj)) {
|
|
727
|
+
const names = [str(cs.source), str(cs.id)].filter(Boolean);
|
|
728
|
+
for (const iface of arr(asked?.interfaces).filter(isObj)) {
|
|
729
|
+
for (const ex of arr(iface.exchanges).filter(isObj)) {
|
|
730
|
+
const keys = ["/", ".", ":"].map((sep) => `${str(iface.name)}${sep}${str(ex.id)}`);
|
|
731
|
+
if (names.some((n) => keys.includes(n)) && move(ex, cs.verdict) && asked)
|
|
732
|
+
asked.from = unique([...asked.from, id]);
|
|
733
|
+
}
|
|
734
|
+
}
|
|
735
|
+
for (const o of arr(sells?.offerings).filter(isObj)) {
|
|
736
|
+
const keys = [str(o.id), `offering:${str(o.id)}`, `offerings/${str(o.id)}`];
|
|
737
|
+
if (o.id !== undefined && names.some((n) => keys.includes(n)) && move(o, cs.verdict) && sells)
|
|
738
|
+
sells.from = unique([...sells.from, id]);
|
|
739
|
+
}
|
|
740
|
+
}
|
|
741
|
+
// An open-with-focus offering's result on an evaluation set: the record's own counts, cited, never rounded into a rating (Section 9.5).
|
|
742
|
+
if (sells && text(r.offering) && isObj(r.evaluation_set) && isObj(r.result)) {
|
|
743
|
+
const o = arr(sells.offerings).filter(isObj).find((x) => x.id === r.offering);
|
|
744
|
+
if (o) {
|
|
745
|
+
o.evaluated_against = [...arr(o.evaluated_against), { set: r.evaluation_set, result: r.result, record: id }];
|
|
746
|
+
sells.from = unique([...sells.from, id]);
|
|
747
|
+
}
|
|
748
|
+
}
|
|
749
|
+
}
|
|
750
|
+
if (entries.length)
|
|
751
|
+
sections.standing = { ...standing, entries };
|
|
752
|
+
}
|
|
753
|
+
/** Attestations: carried, attributed and never audited (Section 9.5, standing). A failed one is shown, not dropped (Section 8.1). */
|
|
754
|
+
function applyAttestations(ctx, sections, attestations) {
|
|
755
|
+
if (!attestations.length)
|
|
756
|
+
return;
|
|
757
|
+
const standing = sections.standing ?? { from: [] };
|
|
758
|
+
const entries = arr(standing.entries);
|
|
759
|
+
for (const a of attestations) {
|
|
760
|
+
const opened = openAttestation(a);
|
|
761
|
+
const id = newId(ctx, "attestation");
|
|
762
|
+
const state = opened?.check.state ?? "failed";
|
|
763
|
+
ctx.sources.push({ id, kind: "attestation", fetched_at: ctx.now, digest: digestOf(a), signature: state });
|
|
764
|
+
standing.from = unique([...standing.from, id]);
|
|
765
|
+
if (!opened) {
|
|
766
|
+
entries.push({ kind: "attestation", signature: state, record: id });
|
|
767
|
+
ctx.notes.push("An attestation could not be read; it is listed as failed.");
|
|
768
|
+
continue;
|
|
769
|
+
}
|
|
770
|
+
const st = opened.statement;
|
|
771
|
+
const pr = isObj(st.predicate) ? st.predicate : st;
|
|
772
|
+
const attester = isObj(pr.attester) ? pr.attester : undefined;
|
|
773
|
+
const subj = arr(st.subject).filter(isObj)[0];
|
|
774
|
+
const areas = {};
|
|
775
|
+
if (isObj(pr.areas))
|
|
776
|
+
for (const [k, v] of Object.entries(pr.areas))
|
|
777
|
+
areas[k] = isObj(v) ? v.result : v;
|
|
778
|
+
entries.push({
|
|
779
|
+
kind: "attestation",
|
|
780
|
+
...(attester && text(attester.name) ? { by: attester.name } : text(pr.by) ? { by: pr.by } : opened.check.by ? { by: opened.check.by } : {}),
|
|
781
|
+
...(attester && text(attester.id) ? { by_key: attester.id } : {}),
|
|
782
|
+
...(subj ? { about: { ...(text(subj.name) ? { name: subj.name } : {}), ...(isObj(subj.digest) && text(subj.digest.sha256) ? { sha256: subj.digest.sha256 } : {}) } } : {}),
|
|
783
|
+
...(text(pr.checked_at) ?? text(pr.produced_at) ? { as_of: text(pr.checked_at) ?? text(pr.produced_at) } : {}),
|
|
784
|
+
...(text(pr.expires_at) ? { expires_at: pr.expires_at } : {}),
|
|
785
|
+
...(Object.keys(areas).length ? { areas } : {}),
|
|
786
|
+
...(text(pr.words) ? { words: pr.words } : {}),
|
|
787
|
+
signature: state,
|
|
788
|
+
record: id,
|
|
789
|
+
});
|
|
790
|
+
}
|
|
791
|
+
sections.standing = { ...standing, entries };
|
|
792
|
+
}
|
|
793
|
+
// ── silence, printed ────────────────────────────────────────────────────────
|
|
794
|
+
/**
|
|
795
|
+
* The paths a document names in `not_stated`: every section nobody sourced,
|
|
796
|
+
* and every member Section 9 says a reader must be told is missing.
|
|
797
|
+
*/
|
|
798
|
+
export function notStatedOf(sections, opts) {
|
|
799
|
+
const out = [];
|
|
800
|
+
if (opts.pkg)
|
|
801
|
+
out.push("subject");
|
|
802
|
+
const add = (p) => {
|
|
803
|
+
if (!covered(out, [p]))
|
|
804
|
+
out.push(p);
|
|
805
|
+
};
|
|
806
|
+
for (const name of KNOWN_SECTIONS)
|
|
807
|
+
if (!sections[name])
|
|
808
|
+
add(name);
|
|
809
|
+
const id = sections.identity;
|
|
810
|
+
if (id)
|
|
811
|
+
for (const m of ["name", "operator", "acts_for"])
|
|
812
|
+
if (id[m] === undefined)
|
|
813
|
+
add(`identity.${m}`);
|
|
814
|
+
if (sections.shape && sections.shape.visibility === undefined)
|
|
815
|
+
add("shape.visibility");
|
|
816
|
+
const access = sections.access;
|
|
817
|
+
if (access)
|
|
818
|
+
for (const m of ["schemes", "admission"])
|
|
819
|
+
if (access[m] === undefined)
|
|
820
|
+
add(`access.${m}`);
|
|
821
|
+
const offerings = arr(sections.sells?.offerings).filter(isObj);
|
|
822
|
+
const members = ["inputs", "outputs", ...(opts.pkg ? [] : ["price"])];
|
|
823
|
+
for (const m of members) {
|
|
824
|
+
const lacking = offerings.filter((o) => o[m] === undefined && !(m === "outputs" && o.deliverables !== undefined));
|
|
825
|
+
if (!lacking.length)
|
|
826
|
+
continue;
|
|
827
|
+
if (lacking.length === offerings.length && offerings.length > 1)
|
|
828
|
+
add(`sells.offerings.${m}`);
|
|
829
|
+
else
|
|
830
|
+
for (const o of lacking)
|
|
831
|
+
add(offeringPaths(o, m)[0]);
|
|
832
|
+
}
|
|
833
|
+
if (opts.pkg)
|
|
834
|
+
add("sells.offerings.price");
|
|
835
|
+
if (opts.pkg)
|
|
836
|
+
add("shape.visibility");
|
|
837
|
+
if (sections.sells)
|
|
838
|
+
add("sells.samples");
|
|
839
|
+
for (const i of arr(sections.asked?.interfaces).filter(isObj))
|
|
840
|
+
if (!arr(i.exchanges).length)
|
|
841
|
+
add(`asked.${str(i.name)}`);
|
|
842
|
+
const configs = sections.configs;
|
|
843
|
+
if (configs && arr(configs.settings).length && configs.tested_models === undefined)
|
|
844
|
+
add("configs.tested_models");
|
|
845
|
+
const handling = sections.handling;
|
|
846
|
+
if (handling)
|
|
847
|
+
for (const m of ["processed_in", "retention_max_days", "processors", "memory"])
|
|
848
|
+
if (handling[m] === undefined)
|
|
849
|
+
add(`handling.${m}`);
|
|
850
|
+
return out;
|
|
851
|
+
}
|
|
852
|
+
// ── the package AgentDoc (Section 13.4) ────────────────────────────────────
|
|
853
|
+
/**
|
|
854
|
+
* A package AgentDoc: assembled from the package's manifest and its draft
|
|
855
|
+
* Descriptor alone, with `package` in place of `subject`, no assembly time
|
|
856
|
+
* and no fetch time, so the same package always gives the same bytes. It
|
|
857
|
+
* carries no subject, access, standing, price or handling, and names each.
|
|
858
|
+
*/
|
|
859
|
+
async function assemblePackage(input, ctx) {
|
|
860
|
+
if (input.descriptor === undefined)
|
|
861
|
+
throw new AssembleError("A package AgentDoc needs the package's draft Descriptor as well as its manifest.");
|
|
862
|
+
const man = await load(input.package, ctx.f, ctx.now, "package manifest");
|
|
863
|
+
const desc = await load(input.descriptor, ctx.f, ctx.now, "Descriptor");
|
|
864
|
+
const m = isObj(man.value) ? man.value : {};
|
|
865
|
+
const d = isObj(desc.value) ? desc.value : null;
|
|
866
|
+
if (!d || d.format !== "agent-descriptor-v1")
|
|
867
|
+
throw new AssembleError("The package's Descriptor is not an agent-descriptor-v1 document.");
|
|
868
|
+
if (isObj(d.subject) && d.subject.id !== undefined) {
|
|
869
|
+
throw new AssembleError("This Descriptor names a subject, so it describes an agent that exists. A package AgentDoc describes no running agent (Section 13.4).");
|
|
870
|
+
}
|
|
871
|
+
const descEntry = sourceEntry(newId(ctx, "descriptor"), "agent-descriptor", desc, "unsigned", false);
|
|
872
|
+
if (d.agent_version !== undefined)
|
|
873
|
+
descEntry.agent_version = String(d.agent_version);
|
|
874
|
+
const pkgEntry = sourceEntry(newId(ctx, "package"), "plugin-package", man, "unsigned", false);
|
|
875
|
+
if (text(m.version))
|
|
876
|
+
pkgEntry.agent_version = String(m.version);
|
|
877
|
+
// The manifest points at its Descriptor by digest; a package paired with another Descriptor names the wrong agent.
|
|
878
|
+
const ext = isObj(m.extensions) && isObj(m.extensions["net.agentdoc.package"]) ? m.extensions["net.agentdoc.package"] : {};
|
|
879
|
+
const pointed = isObj(ext.descriptor) ? text(ext.descriptor.sha256) : undefined;
|
|
880
|
+
if (pointed && `sha256:${pointed.replace(/^sha256:/, "")}` !== desc.digest) {
|
|
881
|
+
pkgEntry.disagreements = [`the manifest points at Descriptor sha256:${pointed.replace(/^sha256:/, "")}, and the Descriptor given is ${desc.digest}`];
|
|
882
|
+
ctx.notes.push(`Disagreement: ${pkgEntry.disagreements[0]}.`);
|
|
883
|
+
}
|
|
884
|
+
ctx.sources.push(descEntry, pkgEntry);
|
|
885
|
+
const descId = descEntry.id;
|
|
886
|
+
const pkgId = pkgEntry.id;
|
|
887
|
+
const sections = {};
|
|
888
|
+
const identity = new Section();
|
|
889
|
+
identity.put("name", text(m.name), pkgId);
|
|
890
|
+
identity.put("description", text(d.does) ?? text(m.description), text(d.does) ? descId : pkgId);
|
|
891
|
+
identity.put("version", text(m.version) ?? (d.agent_version !== undefined ? String(d.agent_version) : undefined), text(m.version) ? pkgId : descId);
|
|
892
|
+
setSection(sections, "identity", identity);
|
|
893
|
+
if (typeof d.interaction === "string" && INTERACTION.includes(d.interaction)) {
|
|
894
|
+
const shape = new Section();
|
|
895
|
+
shape.put("interaction", d.interaction, descId);
|
|
896
|
+
setSection(sections, "shape", shape);
|
|
897
|
+
}
|
|
898
|
+
descriptorSections(sections, d, descId);
|
|
899
|
+
if (arr(d.interfaces).length)
|
|
900
|
+
sections.asked = await askedSection(ctx, d, descId, false);
|
|
901
|
+
const list = arr(d.offerings).filter(isObj).map(sellsOffering);
|
|
902
|
+
if (list.length) {
|
|
903
|
+
const sells = new Section();
|
|
904
|
+
sells.put("scopes", unique(list.map((o) => str(o.scope))), descId);
|
|
905
|
+
sells.put("offerings", list, descId);
|
|
906
|
+
setSection(sections, "sells", sells);
|
|
907
|
+
}
|
|
908
|
+
const doc = {
|
|
909
|
+
agentdoc: "v1",
|
|
910
|
+
package: { ...(text(m.name) ? { name: String(m.name) } : {}), ...(text(m.version) ? { version: String(m.version) } : {}) },
|
|
911
|
+
assembled_by: input.assembledBy ?? `@common-agent/agentdoc ${VERSION}; assembled from the package, not signed`,
|
|
912
|
+
sources: ctx.sources,
|
|
913
|
+
sections,
|
|
914
|
+
not_stated: notStatedOf(sections, { pkg: true, card: false }),
|
|
915
|
+
signatures: [],
|
|
916
|
+
};
|
|
917
|
+
return { doc, notes: ctx.notes };
|
|
918
|
+
}
|