@common-agent/agentdoc 0.1.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/dist/assemble.js +34 -1
- package/dist/check.js +7 -0
- package/dist/cli.d.ts +1 -1
- package/dist/descriptor.js +12 -0
- package/dist/paths.d.ts +1 -1
- package/dist/paths.js +1 -1
- package/dist/render.d.ts +3 -3
- package/dist/render.js +37 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
- package/schema/agentdoc-v1.schema.json +1 -0
package/dist/assemble.js
CHANGED
|
@@ -45,6 +45,9 @@ const AUTHORITY = ["reads-files", "writes-files", "reads-systems", "updates-syst
|
|
|
45
45
|
const CEILINGS = ["job_seconds", "cost_per_job", "spend_per_job", "messages_per_job"];
|
|
46
46
|
const TRIAL_WHO = ["anyone", "signed_in", "verified"];
|
|
47
47
|
const TRIAL_COUNTS = ["per_requester_per_day", "per_day", "per_requester_ever"];
|
|
48
|
+
/** The values of a schedule's `every` and of `contacts` (Section 6.2); any other value is read as not stated. */
|
|
49
|
+
const EVERY = ["hour", "day", "week", "month"];
|
|
50
|
+
const CONTACTS = ["owner", "callers", "named", "anyone"];
|
|
48
51
|
/** What an open-ended offering never carries: any statement of what it can do (Section 9.5). */
|
|
49
52
|
export const OPEN_ENDED_CLAIMS = ["does", "focus", "role", "can_do", "capabilities", "skills", "examples", "tags"];
|
|
50
53
|
/**
|
|
@@ -534,7 +537,7 @@ function buildSells(ctx, c, cardId, d, descId) {
|
|
|
534
537
|
void ctx;
|
|
535
538
|
return { list: [], src: "" };
|
|
536
539
|
}
|
|
537
|
-
/** The sections only a Descriptor fills: role, refuses, reaches, leaves and
|
|
540
|
+
/** The sections only a Descriptor fills: role, refuses, reaches, leaves, configs and triggers. */
|
|
538
541
|
function descriptorSections(sections, d, descId) {
|
|
539
542
|
if (text(d.role)) {
|
|
540
543
|
const role = new Section();
|
|
@@ -584,6 +587,28 @@ function descriptorSections(sections, d, descId) {
|
|
|
584
587
|
if (rc && typeof rc.replay === "boolean")
|
|
585
588
|
configs.put("replay", rc.replay, descId);
|
|
586
589
|
setSection(sections, "configs", configs);
|
|
590
|
+
// triggers: what makes it act when nobody has asked (Section 6.2), quoted, each event and schedule at declared. An
|
|
591
|
+
// `every` or a contact this version does not list is read as not stated, never as the nearest value it does list.
|
|
592
|
+
if (isObj(d.triggers)) {
|
|
593
|
+
const t = d.triggers;
|
|
594
|
+
const triggers = new Section();
|
|
595
|
+
if (Array.isArray(t.events))
|
|
596
|
+
triggers.put("events", t.events.filter(isObj).map((e) => ({ ...e, state: "declared" })), descId);
|
|
597
|
+
if (Array.isArray(t.schedules)) {
|
|
598
|
+
triggers.put("schedules", t.schedules.filter(isObj).map((x) => {
|
|
599
|
+
const { every, ...rest } = x;
|
|
600
|
+
return { ...(EVERY.includes(str(every)) ? { every } : {}), ...rest, state: "declared" };
|
|
601
|
+
}), descId);
|
|
602
|
+
}
|
|
603
|
+
if (typeof t.sets_own === "boolean")
|
|
604
|
+
triggers.put("sets_own", t.sets_own, descId);
|
|
605
|
+
if (Array.isArray(t.contacts)) {
|
|
606
|
+
const known = t.contacts.filter((c) => CONTACTS.includes(str(c)));
|
|
607
|
+
if (known.length || !t.contacts.length)
|
|
608
|
+
triggers.put("contacts", known, descId);
|
|
609
|
+
}
|
|
610
|
+
setSection(sections, "triggers", triggers);
|
|
611
|
+
}
|
|
587
612
|
}
|
|
588
613
|
/** The `asked` section: every declared interface, each with the exchanges its definition publishes, each at `declared`. */
|
|
589
614
|
async function askedSection(ctx, d, descId, resolve) {
|
|
@@ -842,11 +867,19 @@ export function notStatedOf(sections, opts) {
|
|
|
842
867
|
const configs = sections.configs;
|
|
843
868
|
if (configs && arr(configs.settings).length && configs.tested_models === undefined)
|
|
844
869
|
add("configs.tested_models");
|
|
870
|
+
const triggers = sections.triggers;
|
|
871
|
+
if (triggers)
|
|
872
|
+
for (const m of ["events", "schedules", "sets_own", "contacts"])
|
|
873
|
+
if (triggers[m] === undefined)
|
|
874
|
+
add(`triggers.${m}`);
|
|
845
875
|
const handling = sections.handling;
|
|
846
876
|
if (handling)
|
|
847
877
|
for (const m of ["processed_in", "retention_max_days", "processors", "memory"])
|
|
848
878
|
if (handling[m] === undefined)
|
|
849
879
|
add(`handling.${m}`);
|
|
880
|
+
// whose jobs it learns from is asked only of an agent that remembers across jobs (Section 6.9)
|
|
881
|
+
if (handling && handling.memory === "remembers-across-jobs" && handling.memory_pool === undefined)
|
|
882
|
+
add("handling.memory_pool");
|
|
850
883
|
return out;
|
|
851
884
|
}
|
|
852
885
|
// ── the package AgentDoc (Section 13.4) ────────────────────────────────────
|
package/dist/check.js
CHANGED
|
@@ -195,6 +195,13 @@ export function staticFindings(doc) {
|
|
|
195
195
|
need("access.schemes", isObj(sections.access) && sections.access.schemes !== undefined);
|
|
196
196
|
need("access.admission", isObj(sections.access) && sections.access.admission !== undefined);
|
|
197
197
|
}
|
|
198
|
+
// a triggers section names each member the Descriptor left out (Section 9.5)
|
|
199
|
+
if (isObj(sections.triggers))
|
|
200
|
+
for (const m of ["events", "schedules", "sets_own", "contacts"])
|
|
201
|
+
need(`triggers.${m}`, sections.triggers[m] !== undefined);
|
|
202
|
+
// whose jobs it learns from, where it remembers across jobs (Sections 6.9 and 9.5)
|
|
203
|
+
if (isObj(sections.handling) && sections.handling.memory === "remembers-across-jobs")
|
|
204
|
+
need("handling.memory_pool", sections.handling.memory_pool !== undefined);
|
|
198
205
|
const interfaces = isObj(sections.asked) ? arr(sections.asked.interfaces) : [];
|
|
199
206
|
for (const iface of interfaces) {
|
|
200
207
|
if (isObj(iface) && isStr(iface.name))
|
package/dist/cli.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export declare const USAGE = "common-agent-doc 0.
|
|
1
|
+
export declare const USAGE = "common-agent-doc 0.2.0: make, publish and check an AgentDoc.\n\nAn AgentDoc is one document that says what an agent is, what it offers and\nwhat it refuses, built only from what the agent itself publishes. Every line\nsays where it came from, and anything the agent has not said is listed as\nnot stated. See https://agentdoc.net\n\nCommands:\n build <address | card file> write the AgentDoc and its page\n check <file | url> check an AgentDoc against Section 9.10\n init <address | card file> draft a Descriptor from the agent's card\n keygen make the agent's signing key\n sign <descriptor file> sign the Descriptor with that key\n\nRun common-agent-doc <command> --help for the details of one command.";
|
|
2
2
|
/** Where the tool writes, what time it is, and how it fetches: the process's own, unless a test passes others. */
|
|
3
3
|
export interface Io {
|
|
4
4
|
out(line: string): void;
|
package/dist/descriptor.js
CHANGED
|
@@ -49,6 +49,7 @@ export function draftFromCard(card) {
|
|
|
49
49
|
fillIn.push("offerings: the card lists no skills; an empty list says the agent takes no work");
|
|
50
50
|
fillIn.push(`acts_for: whom the agent acts for, one of ${ACTS_FOR.join(", ")} (add organization_name beside organization)`);
|
|
51
51
|
fillIn.push("refusals: what the agent will not do, in your own words");
|
|
52
|
+
fillIn.push('triggers: what makes the agent act when nobody has asked: the events it watches, the schedules it keeps, whether it may set its own (sets_own) and whom it contacts; an agent that acts only when asked says { "events": [], "schedules": [], "sets_own": false }');
|
|
52
53
|
return {
|
|
53
54
|
[DRAFT_MARK]: {
|
|
54
55
|
note: "A draft written from your agent's card by common-agent-doc init. Check every guess, fill in each missing member, then delete this _draft member and sign it with common-agent-doc sign.",
|
|
@@ -98,5 +99,16 @@ export function signingProblems(d) {
|
|
|
98
99
|
});
|
|
99
100
|
if (d.shape !== undefined)
|
|
100
101
|
out.push("shape was removed from the format; take it out (Section 6.12)");
|
|
102
|
+
// every event names a system the Descriptor declares, because watching a system is reaching it (Section 6.2)
|
|
103
|
+
if (isObj(d.triggers) && Array.isArray(d.triggers.events)) {
|
|
104
|
+
const systems = arr(d.systems).filter(isObj).map((s) => str(s.name ?? s.role));
|
|
105
|
+
d.triggers.events.forEach((e, i) => {
|
|
106
|
+
const sys = isObj(e) ? str(e.system) : "";
|
|
107
|
+
if (!sys)
|
|
108
|
+
out.push(`trigger event ${i + 1} names no system`);
|
|
109
|
+
else if (!systems.includes(sys))
|
|
110
|
+
out.push(`trigger event ${i + 1} comes from ${sys}, which systems does not declare`);
|
|
111
|
+
});
|
|
112
|
+
}
|
|
101
113
|
return out;
|
|
102
114
|
}
|
package/dist/paths.d.ts
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
*/
|
|
13
13
|
import { type Rec } from "./util.js";
|
|
14
14
|
/** The sections of Section 9.5, in the order a reader meets them. */
|
|
15
|
-
export declare const KNOWN_SECTIONS: readonly ["identity", "shape", "asked", "role", "sells", "access", "refuses", "reaches", "leaves", "configs", "handling", "standing"];
|
|
15
|
+
export declare const KNOWN_SECTIONS: readonly ["identity", "shape", "asked", "role", "sells", "access", "refuses", "reaches", "leaves", "configs", "triggers", "handling", "standing"];
|
|
16
16
|
/** Every value present at a path; empty when nothing is there. */
|
|
17
17
|
export declare function valuesAt(doc: Rec, path: string): unknown[];
|
|
18
18
|
/** Whether `not_stated` names one of these paths or a path above one of them. */
|
package/dist/paths.js
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
*/
|
|
13
13
|
import { isObj } from "./util.js";
|
|
14
14
|
/** The sections of Section 9.5, in the order a reader meets them. */
|
|
15
|
-
export const KNOWN_SECTIONS = ["identity", "shape", "asked", "role", "sells", "access", "refuses", "reaches", "leaves", "configs", "handling", "standing"];
|
|
15
|
+
export const KNOWN_SECTIONS = ["identity", "shape", "asked", "role", "sells", "access", "refuses", "reaches", "leaves", "configs", "triggers", "handling", "standing"];
|
|
16
16
|
const isSection = (doc, word) => KNOWN_SECTIONS.includes(word) || (isObj(doc.sections) && Object.prototype.hasOwnProperty.call(doc.sections, word));
|
|
17
17
|
function step(v, segs, parent) {
|
|
18
18
|
if (v === undefined)
|
package/dist/render.d.ts
CHANGED
|
@@ -6,10 +6,10 @@
|
|
|
6
6
|
* from; `not_stated` is shown as plainly as what was stated; the assembly time
|
|
7
7
|
* is shown, and `stale_after` where there is one; nothing is added that the
|
|
8
8
|
* document does not hold, so there is no badge, score or trust mark. And the
|
|
9
|
-
*
|
|
9
|
+
* five differences that vanish once lost: an absent `reaches` is not an empty
|
|
10
10
|
* reach, a grant is shown apart from a file, an absent `access` is not an open
|
|
11
|
-
* door,
|
|
12
|
-
*
|
|
11
|
+
* door, an open offering is shown with its scope in words, never as a list of
|
|
12
|
+
* work it can do, and an absent `triggers` is no promise to wait to be asked.
|
|
13
13
|
*
|
|
14
14
|
* Nothing is presented above what `shape.visibility` supports (Section
|
|
15
15
|
* 9.5.1). A ceiling decided by rule is shown as the operator's word that a
|
package/dist/render.js
CHANGED
|
@@ -53,11 +53,17 @@ function notStatedWords(p) {
|
|
|
53
53
|
leaves: ["what records a job leaves", "no records are declared"],
|
|
54
54
|
configs: ["what a job may set", "nothing says which settings a job may choose"],
|
|
55
55
|
"configs.tested_models": ["which models were tested", "settings are declared, and no tested models are listed, so treat every model as untested"],
|
|
56
|
+
triggers: ["what makes it act when nobody asks", "it has not said. That is no promise that it waits to be asked."],
|
|
57
|
+
"triggers.events": ["which events it watches", "it has not said which events make it act"],
|
|
58
|
+
"triggers.schedules": ["which schedules it keeps", "it has not said whether it acts on a schedule"],
|
|
59
|
+
"triggers.sets_own": ["whether it sets schedules of its own", "it has not said whether it may set reminders for itself"],
|
|
60
|
+
"triggers.contacts": ["whom it contacts when it acts", "it has not said whom it contacts when it acts on its own"],
|
|
56
61
|
handling: ["where your content goes and how long it is kept", "nothing says where content is processed or kept. It has promised to delete nothing."],
|
|
57
62
|
"handling.processed_in": ["where your content is processed", "no place is named, so it may be anywhere"],
|
|
58
63
|
"handling.retention_max_days": ["how long it keeps what you send", "it has promised to delete nothing"],
|
|
59
64
|
"handling.processors": ["which services see your content", "no processors are named"],
|
|
60
65
|
"handling.memory": ["whether it remembers one job in the next", "it has not said, so do not assume each job starts clean"],
|
|
66
|
+
"handling.memory_pool": ["whose jobs it learns from", "it remembers across jobs and has not said whether what it keeps from one caller's jobs is used for another's"],
|
|
61
67
|
standing: ["what others have published about it", "no attestation, evaluation or report was read"],
|
|
62
68
|
subject: ["which agent this is", "a package describes no running agent until someone installs it"],
|
|
63
69
|
};
|
|
@@ -84,6 +90,21 @@ const AUTHORITY_WORDS = {
|
|
|
84
90
|
"sends-messages": "sends messages to parties other than you",
|
|
85
91
|
"spends-money": "commits money on your or its owner's behalf",
|
|
86
92
|
};
|
|
93
|
+
const EVERY_WORDS = { hour: "every hour", day: "every day", week: "every week", month: "every month" };
|
|
94
|
+
const CONTACT_WORDS = {
|
|
95
|
+
owner: "its owner",
|
|
96
|
+
callers: "the parties it holds work for",
|
|
97
|
+
named: "parties its owner names",
|
|
98
|
+
anyone: "parties it has not dealt with before",
|
|
99
|
+
};
|
|
100
|
+
const MEMORY_WORDS = {
|
|
101
|
+
"remembers-across-jobs": "it keeps what a job was given or learned for later jobs",
|
|
102
|
+
"starts-clean-each-job": "every job starts with nothing from an earlier one",
|
|
103
|
+
};
|
|
104
|
+
const POOL_WORDS = {
|
|
105
|
+
"each-caller": "what it keeps from your jobs is used only in your later jobs",
|
|
106
|
+
"every-caller": "what it keeps from every caller's jobs is used in every caller's later jobs, yours included",
|
|
107
|
+
};
|
|
87
108
|
const CEILING_WORDS = {
|
|
88
109
|
job_seconds: "seconds one job runs",
|
|
89
110
|
cost_per_job: "what one job costs you",
|
|
@@ -269,6 +290,17 @@ export function render(doc) {
|
|
|
269
290
|
? table(["Setting", "Kind", "Default", "Allowed", "A sender may set it"], settings.map((x) => [`<code>${esc(x.name)}</code>`, esc(x.kind), esc(words(x.default)), esc(Array.isArray(x.allowed) ? words(x.allowed.map((a) => (x.name === "model" && s.configs?.tested_models !== undefined && !tested.includes(String(a)) ? `${a} (untested)` : a))) : "not listed"), x.job_may_set === true ? "yes" : "no"]))
|
|
270
291
|
+ (arr(s.configs?.named).length ? `<h4>Named run configs</h4><ul>${arr(s.configs?.named).filter(isObj).map((n) => `<li>${esc(n.name)} <code>${esc(shortDigest(n.digest))}</code></li>`).join("")}</ul>` : "")
|
|
271
292
|
: p("It takes no settings.");
|
|
293
|
+
const trig = s.triggers ?? {};
|
|
294
|
+
const events = arr(trig.events).filter(isObj);
|
|
295
|
+
const schedules = arr(trig.schedules).filter(isObj);
|
|
296
|
+
const onlyAsked = trig.events !== undefined && trig.schedules !== undefined && !events.length && !schedules.length && trig.sets_own === false;
|
|
297
|
+
const triggersBody = (onlyAsked
|
|
298
|
+
? p("It acts only when it is sent a request.")
|
|
299
|
+
: (events.length ? `<h4>Events it watches</h4>${table(["System", "Event", "What it does"], events.map((e) => [esc(str(e.system) || "not stated"), `<code>${esc(e.kind)}</code>`, esc(e.does)]))}` : trig.events !== undefined ? p("It watches no events.") : "")
|
|
300
|
+
+ (schedules.length ? `<h4>Schedules it keeps</h4>${table(["How often", "What it does"], schedules.map((x) => [esc(EVERY_WORDS[str(x.every)] ?? "not stated"), esc(x.does)]))}` : trig.schedules !== undefined ? p("It keeps no schedules.") : "")
|
|
301
|
+
+ (typeof trig.sets_own === "boolean" ? p(trig.sets_own ? "It may set schedules and reminders of its own while it works." : "It does not set schedules of its own.") : ""))
|
|
302
|
+
+ (Array.isArray(trig.contacts) ? p(trig.contacts.length ? `When it acts on its own, it contacts ${esc(joinWords(trig.contacts.map((c) => CONTACT_WORDS[str(c)] ?? str(c))))}.` : "When it acts on its own, it contacts nobody.") : "")
|
|
303
|
+
+ note("The operator's own word. Nothing here has seen it act.");
|
|
272
304
|
const handling = s.handling ?? {};
|
|
273
305
|
const handlingRows = [];
|
|
274
306
|
if (handling.hosted_in)
|
|
@@ -277,6 +309,10 @@ export function render(doc) {
|
|
|
277
309
|
handlingRows.push(["Kept for", typeof handling.retention_max_days === "number" ? `at most ${esc(handling.retention_max_days)} days` : `<span class="tag">not stated</span> it has promised to delete nothing`]);
|
|
278
310
|
if (Array.isArray(handling.processors))
|
|
279
311
|
handlingRows.push(["Seen by", esc(joinWords(handling.processors.map((x) => (isObj(x) ? [str(x.service), str(x.purpose)].filter(Boolean).join(", for ") : String(x)))) || "no other service")]);
|
|
312
|
+
if (MEMORY_WORDS[str(handling.memory)])
|
|
313
|
+
handlingRows.push(["Between jobs", esc(MEMORY_WORDS[str(handling.memory)])]);
|
|
314
|
+
if (POOL_WORDS[str(handling.memory_pool)])
|
|
315
|
+
handlingRows.push(["Whose jobs it learns from", esc(POOL_WORDS[str(handling.memory_pool)])]);
|
|
280
316
|
if (isObj(handling.promises))
|
|
281
317
|
handlingRows.push(["It promises", esc(Object.entries(handling.promises).filter(([k, v]) => k !== "grade" && v === true).map(([k]) => k.replace(/_/g, " ")).join("; ") + (typeof handling.promises.grade === "string" ? ` (graded ${handling.promises.grade})` : ""))]);
|
|
282
318
|
const handlingBody = `<table><tbody>${handlingRows.map((r) => `<tr><th>${esc(r[0])}</th><td>${r[1]}</td></tr>`).join("")}</tbody></table>`;
|
|
@@ -354,6 +390,7 @@ ${band("refuses", "What it refuses", s.refuses, refusesBody)}
|
|
|
354
390
|
${band("reaches", "What it reaches", s.reaches, reachesBody)}
|
|
355
391
|
${band("leaves", "Records a job leaves", s.leaves, recordsBody)}
|
|
356
392
|
${band("configs", "What a job may set", s.configs, configsBody)}
|
|
393
|
+
${band("triggers", "When it acts on its own", s.triggers, triggersBody)}
|
|
357
394
|
${isPackage ? "" : band("handling", "Where your content goes", s.handling, handlingBody)}
|
|
358
395
|
${isPackage ? "" : band("standing", "Checked by others", s.standing, standingBody)}
|
|
359
396
|
<details open id="not-stated" class="band"><summary><h2>Not stated</h2><span class="from">${notStated.length} question${notStated.length === 1 ? "" : "s"} the sources leave open</span></summary><div class="body">${notStatedBody}</div></details>
|
package/dist/version.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** This package's version, which an assembly names as its assembler. A test holds it to package.json. */
|
|
2
|
-
export declare const VERSION = "0.
|
|
2
|
+
export declare const VERSION = "0.2.0";
|
package/dist/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** This package's version, which an assembly names as its assembler. A test holds it to package.json. */
|
|
2
|
-
export const VERSION = "0.
|
|
2
|
+
export const VERSION = "0.2.0";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@common-agent/agentdoc",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Make, publish and check an AgentDoc: one document that says what an agent is, what it offers and what it refuses, assembled from its A2A card and signed Descriptor, with a small command line tool.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"common-agent",
|
|
@@ -42,6 +42,7 @@
|
|
|
42
42
|
"reaches": { "$ref": "#/$defs/section" },
|
|
43
43
|
"leaves": { "$ref": "#/$defs/section" },
|
|
44
44
|
"configs": { "$ref": "#/$defs/section" },
|
|
45
|
+
"triggers": { "$ref": "#/$defs/section" },
|
|
45
46
|
"handling": { "$ref": "#/$defs/section" },
|
|
46
47
|
"standing": { "$ref": "#/$defs/section" }
|
|
47
48
|
},
|