Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/SPEC-NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,26 @@ because there's no host to fetch them from.
- Each `supported_versions` URL MUST be HTTPS on the host that served `poppy.json`.
- Keys are `major.minor`, and name versions *other* than `protocol_version`.

### How Pollen treats other versions

Pollen's rules are the 1.0 rules, and versions before 1.0 differ in breaking ways. For example,
`agent.protocols[].description` became required in 1.0 (changelog, "Conversation protocol
descriptions", breaking), so a valid 0.4 document fails the 1.0 field rules. So:

- A document whose `protocol_version` isn't 1.x fails `version.compatible` (an error): before 1.0 a
version is compatible only with the same minor version, so a Personal Agent that implements only
1.0 MUST NOT use it (3.4).
- Unless `supported_versions` lists a 1.x document: a 1.0 Personal Agent uses that one instead, so
`version.compatible` passes. Pollen doesn't fetch that document yet.
- Either way, the 1.0 field rules and OAuth checks are skipped for a non-1.x document. Only the
rules for what 3.4 says keeps its meaning in every version still run: the location and fetching
of `poppy.json`, `protocol_version`, and `supported_versions`.
- A missing or malformed `protocol_version` fails `version.present` or `version.format`, and the
1.0 rules still run, since there's no other version to judge by.

Found in the wild: Shopify publishes a `poppy.json` for every store, and on 2026-11-17 the ones
checked declared `0.4` with agent entries that have no `description`.

## Score

Not part of the spec; Pollen's own measure. The score starts at 100. Each failed error rule costs
Expand Down
18 changes: 15 additions & 3 deletions src/check.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import { fetchFollowing, parseJson, type Fetcher } from "./fetch.js";
import { RULES } from "./rules/index.js";
import { SPEC_VERSION, WELL_KNOWN_PATH } from "./spec.js";
import type { Context, Report, Rule, RuleResult, Summary } from "./types.js";
import { hostOf, isDomain, isObject } from "./util.js";
import { hostOf, isDomain, isObject, majorOf } from "./util.js";
import { VERSION } from "./version.js";

export interface CheckOptions {
Expand Down Expand Up @@ -73,8 +73,11 @@ export async function check(input: string, options: CheckOptions = {}): Promise<
if (http.status === 200 && !http.error && http.body !== undefined) readText(ctx, http.body);

const org = ctx.doc && isObject(ctx.doc.organization) ? ctx.doc.organization : undefined;
const otherVersion = versionSkip(ctx);
if (!ctx.doc) {
ctx.oauthSkipped = ctx.raw === undefined ? "No document was retrieved." : "No JSON object to check.";
} else if (otherVersion) {
ctx.oauthSkipped = otherVersion;
} else if (options.skipOAuth) {
ctx.oauthSkipped = "Skipped with --skip-oauth.";
} else if (!org || !isDomain(org.domain)) {
Expand Down Expand Up @@ -107,17 +110,26 @@ function readText(ctx: Context, raw: string): void {
if (ctx.parsed.ok && isObject(ctx.parsed.value)) ctx.doc = ctx.parsed.value;
}

/** Why the 1.0 rules don't apply: the document declares a version that isn't 1.x. */
function versionSkip(ctx: Context): string | undefined {
const value = ctx.doc?.protocol_version;
const major = majorOf(value);
if (major === undefined || major === 1) return undefined; // version.present and version.format report bad values
return `protocol_version is ${String(value)}: Pollen applies the ${SPEC_VERSION} rules only to 1.x documents.`;
}

function skipReason(rule: Rule, ctx: Context): string | undefined {
switch (rule.stage) {
case "transport":
return ctx.http ? undefined : "Local file: transport is checked only against a live URL.";
case "parse":
return ctx.raw === undefined ? "No document was retrieved." : undefined;
case "document":
if (ctx.doc) return undefined;
return ctx.raw === undefined ? "No document was retrieved." : "No JSON object to check.";
if (!ctx.doc) return ctx.raw === undefined ? "No document was retrieved." : "No JSON object to check.";
return rule.allVersions ? undefined : versionSkip(ctx);
case "oauth":
if (ctx.oauth) return undefined;
if (versionSkip(ctx)) return versionSkip(ctx);
if (ctx.mode === "file") return "Local file: OAuth metadata is checked only against a live URL.";
return ctx.oauthSkipped ?? "OAuth metadata wasn't fetched.";
}
Expand Down
4 changes: 2 additions & 2 deletions src/report.ts
Original file line number Diff line number Diff line change
Expand Up @@ -66,11 +66,11 @@ export function formatText(report: Report, options: TextOptions = {}): string {
);
if (report.ok) {
const extra = warnings > 0 ? ` Fix the ${plural(warnings, "warning")} to reach 100.` : "";
lines.push(`${paint("green", "PASS")} Personal Agents can use this document.${extra}`);
lines.push(`${paint("green", "PASS")} Poppy ${report.spec_version} Personal Agents can use this document.${extra}`);
} else if (!report.results.some((r) => r.group !== "Transport" && r.status !== "skip")) {
lines.push(`${paint("red", "FAIL")} There's no document Personal Agents can read here.`);
} else {
lines.push(`${paint("red", "FAIL")} Fix the ${plural(errors, "error")} above. Personal Agents won't use this document until then.`);
lines.push(`${paint("red", "FAIL")} Fix the ${plural(errors, "error")} above before Poppy ${report.spec_version} Personal Agents can use this document.`);
}
return `${lines.join("\n")}\n`;
}
Expand Down
1 change: 1 addition & 0 deletions src/rules/define.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ interface RuleSpec {
stage: Stage;
severity: Severity;
section: string;
allVersions?: boolean;
}

export function defineRule(spec: RuleSpec, check: (ctx: Context) => Outcome): Rule {
Expand Down
33 changes: 23 additions & 10 deletions src/rules/document.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
// Section 3.1 and 3.4: protocol_version, organization, and supported_versions.

import { SPEC_VERSION } from "../spec.js";
import { Problems, VERSION_PATTERN, describe, hostOf, isDomain, isObject, show } from "../util.js";
import { CHANGELOG_URL, SPEC_VERSION } from "../spec.js";
import { Problems, VERSION_PATTERN, describe, hostOf, isDomain, isHttpsUrl, isObject, majorOf, show } from "../util.js";
import { VERSION } from "../version.js";
import { defineRule, docOf, fail, pass, skip } from "./define.js";

export const versionPresent = defineRule(
Expand All @@ -12,6 +13,7 @@ export const versionPresent = defineRule(
stage: "document",
severity: "error",
section: "3.1",
allVersions: true,
},
(ctx) => {
const value = docOf(ctx).protocol_version;
Expand All @@ -34,6 +36,7 @@ export const versionFormat = defineRule(
stage: "document",
severity: "error",
section: "3.1",
allVersions: true,
},
(ctx) => {
const value = docOf(ctx).protocol_version;
Expand All @@ -48,25 +51,34 @@ export const versionFormat = defineRule(
export const versionCompatible = defineRule(
{
id: "version.compatible",
title: "protocol_version is a 1.x version",
title: "protocol_version is compatible with 1.0",
group: "Document",
stage: "document",
severity: "warning",
severity: "error",
section: "3.4",
allVersions: true,
},
(ctx) => {
const value = docOf(ctx).protocol_version;
if (typeof value !== "string" || !VERSION_PATTERN.test(value)) return skip("protocol_version isn't valid; see version.format.");
const major = Number(value.split(".")[0]);
const doc = docOf(ctx);
const value = doc.protocol_version;
const major = majorOf(value);
if (major === undefined) return skip("protocol_version isn't valid; see version.format.");
if (major === 1) return pass;
// A 1.0 Personal Agent uses a 1.x document that supported_versions lists instead (spec 3.4).
const versions = doc.supported_versions;
if (isObject(versions) && Object.entries(versions).some(([v, url]) => majorOf(v) === 1 && isHttpsUrl(url))) return pass;
if (major === 0) {
return fail(
"protocol_version",
`${value} is a pre-1.0 draft. Before 1.0, versions are compatible only with the same minor version, so only Personal Agents that implement exactly ${value} will use this document`,
`Update the document to ${SPEC_VERSION}, the current published version. Keep the old one in supported_versions if you still serve it.`,
`${value} is a pre-1.0 draft. Before 1.0, a version is compatible only with the same minor version, so a Personal Agent that implements only ${SPEC_VERSION} must not use this document. Pollen checks ${SPEC_VERSION} documents, so it skipped the field rules`,
`Publish a ${SPEC_VERSION} document: set protocol_version to "${SPEC_VERSION}" and apply the changes since ${value} in the changelog (${CHANGELOG_URL}). To keep serving ${value} as well, move it to another URL and list it in supported_versions. If your platform generates poppy.json for you, it has to make this change.`,
);
}
return fail("protocol_version", `${value} is newer than any published version; Pollen checks against ${SPEC_VERSION}`, `Check the version. The current published version is ${SPEC_VERSION}.`);
return fail(
"protocol_version",
`${value} is a newer major version than ${SPEC_VERSION}, and Pollen ${VERSION} checks only 1.x documents, so it skipped the field rules`,
`Check the version, or use a Pollen release that supports ${major}.x.`,
);
},
);

Expand Down Expand Up @@ -195,6 +207,7 @@ export const supportedVersions = defineRule(
stage: "document",
severity: "error",
section: "3.4",
allVersions: true,
},
(ctx) => {
const doc = docOf(ctx);
Expand Down
1 change: 1 addition & 0 deletions src/spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ export const AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-serve
export const SPEC_BASE = "https://personalagentprotocol.org/docs/1.0/spec";
export const EXTENSIONS_BASE = "https://personalagentprotocol.org/docs/1.0/extensions";
export const ROADMAP_URL = "https://personalagentprotocol.org/docs/introduction#mediated-sign-in";
export const CHANGELOG_URL = "https://personalagentprotocol.org/docs/changelog";

/** Spec section number to its anchor on the spec page. */
export const SECTION_ANCHORS: Record<string, string> = {
Expand Down
6 changes: 6 additions & 0 deletions src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,12 @@ export interface Rule {
section: string;
/** Absolute URL of the section in the spec. */
specUrl: string;
/**
* Runs whatever protocol_version says. Spec 3.4: the document's location and fetching,
* protocol_version, and supported_versions keep their meaning in every version. Other
* document and OAuth rules are 1.0 rules, and only run on 1.x documents.
*/
allVersions?: boolean;
check(ctx: Context): Outcome;
}

Expand Down
5 changes: 5 additions & 0 deletions src/util.ts
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,11 @@ export function isDomain(value: unknown): value is string {

export const VERSION_PATTERN = /^[0-9]+\.[0-9]+$/;

/** The major version of a major.minor string, or undefined if it isn't one. */
export function majorOf(value: unknown): number | undefined {
return typeof value === "string" && VERSION_PATTERN.test(value) ? Number(value.split(".")[0]) : undefined;
}

/** Scope tokens, RFC 6749 §3.3. */
export const SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;

Expand Down
48 changes: 47 additions & 1 deletion tests/check.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import { after, describe, it } from "node:test";
import { check, PENALTIES, resolveTarget, score, TargetError, validateDocument } from "../src/check.js";
import { RULES } from "../src/rules/index.js";
import type { RuleResult } from "../src/types.js";
import { WELL_KNOWN, base, live, make } from "./helpers.js";
import { DOMAIN, ORIGIN, WELL_KNOWN, base, failedErrors, fakeFetcher, live, make, offline, result } from "./helpers.js";

const dir = mkdtempSync(join(tmpdir(), "pollen-check-"));
after(() => rmSync(dir, { recursive: true, force: true }));
Expand Down Expand Up @@ -124,3 +124,49 @@ describe("reports", () => {
assert.equal(report.results.find((x) => x.id === "organization.domain-host")?.status, "fail");
});
});

describe("documents in another version", () => {
// The shape of a 0.4 document: its agent entry has no description, which only 1.0 requires.
const draft = () => ({
protocol_version: "0.4",
organization: { name: "Fern & Finch Bakery", domain: DOMAIN },
agent: { protocols: [{ type: "ucp", endpoint: `${ORIGIN}/.well-known/ucp` }] },
web: {},
extensions: { ucp: [{ version: "1" }] },
});

it("fail version.compatible, not the 1.0 field rules", () => {
const report = offline(draft());
assert.deepEqual(failedErrors(report), ["version.compatible"]);
const agent = result(report, "agent.protocols");
assert.equal(agent.status, "skip");
assert.match(agent.note!, /protocol_version is 0\.4/);
assert.equal(report.score, 75);
});

it("still run the rules every version shares", async () => {
const report = await live(draft());
for (const id of ["transport.https", "transport.status", "transport.final-url", "document.json", "version.present", "version.format"]) {
assert.equal(result(report, id).status, "pass", id);
}
assert.equal(result(report, "versions.supported").note, "No supported_versions (optional).");
});

it("don't fetch OAuth metadata", async () => {
const log: string[] = [];
const report = await check(DOMAIN, { fetcher: fakeFetcher({ [WELL_KNOWN]: { body: draft() } }, log) });
assert.deepEqual(log, [WELL_KNOWN]);
assert.match(result(report, "oauth.issuer").note!, /only to 1\.x documents/);
});

it("are checked against the 1.0 rules when the version is malformed", () => {
const report = offline({ ...draft(), protocol_version: "zero" });
assert.deepEqual(failedErrors(report), ["version.format", "agent.protocols"]);
});

it("pass when supported_versions lists a 1.x document, without checking this one's fields", () => {
const report = offline({ ...draft(), supported_versions: { "1.0": `${ORIGIN}/poppy/1.0.json` } });
assert.deepEqual(failedErrors(report), []);
assert.equal(result(report, "agent.protocols").status, "skip");
});
});
2 changes: 1 addition & 1 deletion tests/cli.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ describe("pollen check", () => {
it("exits 0 for a valid document", async () => {
const { code, stdout } = await run(["check", VALID]);
assert.equal(code, 0);
assert.match(stdout, /PASS {2}Personal Agents can use this document\./);
assert.match(stdout, /PASS {2}Poppy 1\.0 Personal Agents can use this document\./);
});

it("exits 1 for an invalid document and shows the fix", async () => {
Expand Down
23 changes: 23 additions & 0 deletions tests/fixtures/invalid/pre-1.0-version.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"protocol_version": "0.4",
"organization": {
"name": "Fern & Finch Bakery",
"domain": "fernandfinch.example"
},
"agent": {
"protocols": [
{
"type": "ucp",
"endpoint": "https://fernandfinch.example/.well-known/ucp"
}
]
},
"web": {},
"extensions": {
"ucp": [
{
"version": "1"
}
]
}
}
1 change: 1 addition & 0 deletions tests/fixtures/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
"invalid": {
"missing-protocol-version.json": "version.present",
"version-not-major-minor.json": "version.format",
"pre-1.0-version.json": "version.compatible",
"domain-with-scheme.json": "organization.domain",
"supported-version-on-other-host.json": "versions.supported",
"no-channels.json": "channels.present",
Expand Down
2 changes: 1 addition & 1 deletion tests/report.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ describe("formatText", () => {
const text = formatText(broken());
assert.match(text, /Score 70\/100 {3}\d+ passed · 1 error · 1 warning · \d+ skipped/);
assert.match(text, /FAIL {2}Fix the 1 error above/);
assert.match(formatText(offline(base())), /PASS {2}Personal Agents can use this document\.\n$/);
assert.match(formatText(offline(base())), /PASS {2}Poppy 1\.0 Personal Agents can use this document\.\n$/);
});

it("says when there's no document at all", async () => {
Expand Down
7 changes: 6 additions & 1 deletion tests/rules.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -104,8 +104,13 @@ const CASES: Record<string, Case[]> = {
"version.compatible": [
{ name: "1.0", run: () => offline(base()), expect: "pass" },
{ name: "1.1 (draft minor)", run: () => offline(make((d) => (d.protocol_version = "1.1"))), expect: "pass" },
{
name: "0.4 that lists a 1.0 document in supported_versions",
run: () => offline(make((d) => ((d.protocol_version = "0.4"), (d.supported_versions = { "1.0": `${ORIGIN}/poppy/1.0.json` })))),
expect: "pass",
},
{ name: "0.4 (pre-1.0)", run: () => offline(make((d) => (d.protocol_version = "0.4"))), expect: "fail", match: /pre-1\.0/ },
{ name: "2.0 (unknown major)", run: () => offline(make((d) => (d.protocol_version = "2.0"))), expect: "fail", match: /newer than any published/ },
{ name: "2.0 (unknown major)", run: () => offline(make((d) => (d.protocol_version = "2.0"))), expect: "fail", match: /newer major version/ },
{ name: "malformed", run: () => offline(make((d) => (d.protocol_version = "one"))), expect: "skip" },
],
"organization.present": [
Expand Down
Loading