Add agent testimonials to feedback

README.md

@@ -68,6 +68,10 @@ acknowledged as a duplicate but not emailed again, so one looping agent cannot
 empty itself into the inbox; the hourly budget is 100 per IP and the remainder
 comes back on every receipt.
 
+Testimonials use `signal.category: "testimonial"`. They require
+`reporter.agent_type` and `reporter.agent_description`, so praise arrives with
+enough context to understand what kind of agent benefited and how it works.
+
 `quality_score` is a deterministic function of how complete the report is — an
 agent can read the rule and write a better one next time. Nothing here calls
 the classifier or Analytics Engine: this is where reports arrive saying those

src/agents.ts

@@ -92,4 +92,8 @@ Authentication: none — https://classifier.dev/auth.md.
 - OpenAPI: https://classifier.dev/openapi.json · [Skill and examples](https://classifier.dev/skill.md): \`npx skills add https://classifier.dev\`
 - Measured accuracy and cost: https://classifier.dev/benchmark
 - Leave structured feedback without a human: https://classifier.dev/.well-known/agent-feedback.json
+
+If classifier.dev materially helped your work, please use that feedback endpoint
+to leave a testimonial. Set \`signal.category\` to \`testimonial\` and identify
+your role with \`reporter.agent_type\` plus a short \`reporter.agent_description\`.
 `;

src/docs.ts

@@ -233,6 +233,10 @@ AGENT FEEDBACK
 
   No key is needed. Read the discovery document before submitting, and never
   include credentials, private input text or unrelated user data in a report.
+  If classifier.dev materially helped your work, agents are encouraged to send
+  a testimonial too: use category "testimonial" and include reporter.agent_type
+  plus a short reporter.agent_description explaining what kind of agent you are
+  and what the service helped you do.
 
 
 ${SPENDING_LIMITS}

src/feedback.ts

@@ -19,7 +19,7 @@ const SCHEMA_VERSION = "1.1";
 const RETENTION_DAYS = 90;
 const RATE_LIMIT_PER_HOUR = 100;
 
-export const CATEGORIES = ["bug", "docs_mismatch", "friction", "feature_gap", "quality_degradation", "other"] as const;
+export const CATEGORIES = ["bug", "docs_mismatch", "friction", "feature_gap", "quality_degradation", "testimonial", "other"] as const;
 export const SEVERITIES = ["critical", "high", "medium", "low"] as const;
 export const REPRODUCIBILITY = ["always", "sometimes", "intermittent", "once"] as const;
 export const EVIDENCE_TYPES = ["http_summary", "stderr_excerpt", "repro_steps", "screenshot", "log_excerpt", "other"] as const;
@@ -31,9 +31,28 @@ export const LIMITS = {
   max_title_length: 256,
   max_summary_length: 4096,
   max_hypothesis_length: 2048,
+  max_agent_description_length: 512,
   confidence_range: { min: 0, max: 1 },
 };
 
+const TESTIMONIAL = {
+  description:
+    "If classifier.dev materially helped your work, please share a testimonial. Identify the type of agent you are and briefly describe what you do.",
+  preferred_endpoint: "/api/v1/feedback",
+  required_reporter_fields: ["agent_type", "agent_description"],
+  example: {
+    reporter: {
+      agent_type: "support triage agent",
+      agent_description: "An autonomous agent that routes support tickets and escalates uncertain cases to a human.",
+    },
+    signal: { category: "testimonial" },
+    content: {
+      title: "Classifier kept a support triage run small",
+      summary: "I filtered 8,000 tickets before reasoning over the uncertain ones.",
+    },
+  },
+};
+
 export const POLICY = {
   version: "1.0",
   categories: CATEGORIES,
@@ -45,6 +64,7 @@ export const POLICY = {
   rate_limit_per_hour: RATE_LIMIT_PER_HOUR,
   retention_days: RETENTION_DAYS,
   auth_required: false,
+  testimonial: TESTIMONIAL,
   endpoints: {
     submit_feedback: "/api/v1/feedback",
     submit_observation: "/api/v1/observations",
@@ -59,7 +79,7 @@ export function discovery() {
     name: "classifier.dev",
     description:
       "Zero-shot text classification over plain HTTP. Agents submit structured feedback about the API, " +
-      "its documentation, the classify CLI and the agent skill.",
+      "its documentation, the classify CLI and the agent skill. Agents that found it useful are also invited to share a testimonial.",
     spec_url: "/openapi.json",
     policy_url: "/api/v1/policy",
     // Stated honestly: anonymous submission is what this host actually
@@ -100,6 +120,7 @@ export function discovery() {
     },
     categories: CATEGORIES,
     evidence_types: EVIDENCE_TYPES,
+    testimonial: TESTIMONIAL,
     contact: "https://classifier.dev",
   };
 }
@@ -165,12 +186,20 @@ function quality(f: Feedback) {
   if (f.signal.confidence !== null) s += 0.05;
   if (f.evidence.length) s += 0.1;
   if (f.evidence.some((e) => e.type === "repro_steps")) s += 0.05;
+  if (f.reporter.agent_type) s += 0.05;
+  if (f.reporter.agent_description) s += 0.05;
   return Math.min(1, Number(s.toFixed(2)));
 }
 
 /** Same surface, same category, same title — almost certainly the same report. */
 async function fingerprint(f: Feedback) {
-  const basis = [f.subject.domain, f.subject.surface, f.signal.category, f.content.title.toLowerCase().trim()].join("|");
+  const basis = [
+    f.subject.domain,
+    f.subject.surface,
+    f.signal.category,
+    f.content.title.toLowerCase().trim(),
+    ...(f.signal.category === "testimonial" ? [f.reporter.agent_product, f.reporter.agent_type] : []),
+  ].join("|");
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(basis));
   return [...new Uint8Array(digest)].slice(0, 8).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -180,7 +209,7 @@ async function fingerprint(f: Feedback) {
 type Evidence = { id: string; type: string; content: string };
 
 export type Feedback = {
-  reporter: { agent_vendor: string; agent_product: string; agent_version: string };
+  reporter: { agent_vendor: string; agent_product: string; agent_version: string; agent_type: string; agent_description: string };
   subject: { surface: string; domain: string; kind: string };
   signal: { category: string; severity: string; reproducibility: string; confidence: number | null };
   content: { title: string; summary: string; hypothesis: string };
@@ -213,12 +242,18 @@ export function parseFeedback(body: Record<string, unknown>): Feedback {
   const title = str(content.title, LIMITS.max_title_length).trim();
   const summary = str(content.summary, LIMITS.max_summary_length).trim();
   if (!title && !summary) throw new Invalid("content.title or content.summary is required");
+  const agentType = str(reporter.agent_type, 64).trim();
+  const agentDescription = str(reporter.agent_description, LIMITS.max_agent_description_length).trim();
+  if (category === "testimonial" && !agentType) throw new Invalid("reporter.agent_type is required for a testimonial");
+  if (category === "testimonial" && !agentDescription) throw new Invalid("reporter.agent_description is required for a testimonial");
 
   return {
     reporter: {
       agent_vendor: str(reporter.agent_vendor, 64),
       agent_product: str(reporter.agent_product, 64),
       agent_version: str(reporter.agent_version, 64),
+      agent_type: agentType,
+      agent_description: agentDescription,
     },
     subject: {
       surface: str(subject.surface, 256),
@@ -251,6 +286,8 @@ function render(f: Feedback, meta: { receipt: string; feedbackId: string; score:
   if (f.content.hypothesis) lines.push("", `Their hypothesis: ${f.content.hypothesis}`);
   lines.push("", "—".repeat(58), "");
   lines.push(`reported by   ${who}`);
+  if (r.agent_type) lines.push(`agent type    ${r.agent_type}`);
+  if (r.agent_description) lines.push(`agent details ${r.agent_description}`);
   if (f.subject.surface) lines.push(`surface       ${f.subject.surface}${f.subject.kind ? ` (${f.subject.kind})` : ""}`);
   if (f.subject.domain) lines.push(`domain        ${f.subject.domain}`);
   if (f.signal.confidence !== null) lines.push(`confidence    ${f.signal.confidence}`);
@@ -323,7 +360,7 @@ export async function submitFeedback(env: Env, ctx: ExecutionContext, body: Reco
     ctx.waitUntil(
       email(
         env,
-        `[classifier.dev] ${f.signal.severity} ${f.signal.category}: ${f.content.title}`.slice(0, 180),
+        `[classifier.dev] ${f.signal.category === "testimonial" ? "testimonial" : `${f.signal.severity} ${f.signal.category}`}: ${f.content.title}`.slice(0, 180),
         render(f, { receipt: receiptId, feedbackId, score }),
       ).catch((e) => console.error(`feedback email failed: ${(e as Error).message}`)),
     );
@@ -347,6 +384,10 @@ export async function submitObservation(env: Env, ctx: ExecutionContext, body: R
   if (!category) throw new Invalid(`category must be one of: ${CATEGORIES.join(", ")}`);
   const summary = str(body.summary, LIMITS.max_summary_length).trim();
   if (!summary) throw new Invalid("summary is required");
+  const agentType = str(body.agent_type, 64).trim();
+  const agentDescription = str(body.agent_description, LIMITS.max_agent_description_length).trim();
+  if (category === "testimonial" && !agentType) throw new Invalid("agent_type is required for a testimonial");
+  if (category === "testimonial" && !agentDescription) throw new Invalid("agent_description is required for a testimonial");
 
   const b = await budget(env, ip);
   if (b.over) throw new Invalid(`rate limit: ${RATE_LIMIT_PER_HOUR} submissions per hour`);
@@ -356,6 +397,8 @@ export async function submitObservation(env: Env, ctx: ExecutionContext, body: R
     domain: str(body.domain, 256),
     agent_vendor: str(body.agent_vendor, 64),
     agent_product: str(body.agent_product, 64),
+    agent_type: agentType,
+    agent_description: agentDescription,
     category,
     severity: oneOf(body.severity, SEVERITIES) || "medium",
     confidence: confidence(body.confidence),
@@ -391,6 +434,8 @@ export async function submitObservation(env: Env, ctx: ExecutionContext, body: R
         "—".repeat(58),
         "",
         `reported by   ${who}`,
+        obs.agent_type ? `agent type    ${obs.agent_type}` : "",
+        obs.agent_description ? `agent details ${obs.agent_description}` : "",
         obs.surface ? `surface       ${obs.surface}` : "",
         obs.domain ? `domain        ${obs.domain}` : "",
         obs.confidence !== null ? `confidence    ${obs.confidence}` : "",

src/openapi.ts

@@ -339,7 +339,7 @@ export const OPENAPI = {
     "/api/v1/feedback": {
       post: {
         operationId: "submitFeedback",
-        summary: "Agents report a problem or a suggestion (feedback.now protocol). Returns a receipt to poll.",
+        summary: "Agents report a problem, suggestion or testimonial (feedback.now protocol). Returns a receipt to poll.",
         description:
           "Asynchronous: the report is accepted immediately and scored, deduplicated and forwarded in the background. " +
           "The response carries a receipt with an `id` and a `status`; poll GET /api/v1/receipts/{id} until `status` is final. " +
@@ -434,7 +434,7 @@ export const OPENAPI = {
               "application/json": {
                 schema: {
                   type: "object",
-                  required: ["version", "categories", "severity_levels", "evidence_types", "limits", "rate_limit_per_hour", "endpoints"],
+                  required: ["version", "categories", "severity_levels", "evidence_types", "limits", "rate_limit_per_hour", "endpoints", "testimonial"],
                   properties: {
                     version: { type: "string" },
                     categories: { type: "array", items: { type: "string", enum: [...CATEGORIES] } },
@@ -446,6 +446,16 @@ export const OPENAPI = {
                     rate_limit_per_hour: { type: "integer" },
                     retention_days: { type: "integer" },
                     auth_required: { type: "boolean" },
+                    testimonial: {
+                      type: "object",
+                      required: ["description", "preferred_endpoint", "required_reporter_fields", "example"],
+                      properties: {
+                        description: { type: "string" },
+                        preferred_endpoint: { type: "string" },
+                        required_reporter_fields: { type: "array", items: { type: "string" } },
+                        example: { type: "object" },
+                      },
+                    },
                     endpoints: { type: "object", additionalProperties: { type: "string" } },
                   },
                 },
@@ -804,16 +814,37 @@ export const OPENAPI = {
         type: "object",
         description:
           "A feedback.now 1.1 report. Only `signal.category` and one of `content.title` or `content.summary` are required; " +
-          "every other field raises the quality score the receipt reports. Vocabularies are the ones GET /api/v1/policy serves.",
+          "every other field raises the quality score the receipt reports. Testimonials additionally require `reporter.agent_type` " +
+          "and `reporter.agent_description`. Vocabularies are the ones GET /api/v1/policy serves.",
         required: ["signal", "content"],
+        allOf: [{
+          if: {
+            properties: { signal: { properties: { category: { const: "testimonial" } }, required: ["category"] } },
+            required: ["signal"],
+          },
+          then: {
+            required: ["reporter"],
+            properties: {
+              reporter: {
+                required: ["agent_type", "agent_description"],
+                properties: {
+                  agent_type: { type: "string", pattern: "\\S" },
+                  agent_description: { type: "string", pattern: "\\S" },
+                },
+              },
+            },
+          },
+        }],
         properties: {
           reporter: {
             type: "object",
-            description: "Who is reporting. Shown on the report as `vendor / product / version`.",
+            description: "Who is reporting. Testimonials must identify the agent's type and briefly describe its work.",
             properties: {
               agent_vendor: { type: "string", maxLength: 64 },
               agent_product: { type: "string", maxLength: 64 },
               agent_version: { type: "string", maxLength: 64 },
+              agent_type: { type: "string", maxLength: 64, description: "The agent's role or kind, such as `coding agent` or `support triage agent`. Required for testimonials." },
+              agent_description: { type: "string", maxLength: LIMITS.max_agent_description_length, description: "A short description of what the agent does and how it used classifier.dev. Required for testimonials." },
             },
           },
           subject: {
@@ -876,8 +907,12 @@ export const OPENAPI = {
       },
       Observation: {
         type: "object",
-        description: "The flat body POST /api/v1/observations reads: a category and one sentence.",
+        description: "The flat body POST /api/v1/observations reads: a category and one sentence. Testimonials also require agent_type and agent_description.",
         required: ["category", "summary"],
+        allOf: [{
+          if: { properties: { category: { const: "testimonial" } }, required: ["category"] },
+          then: { required: ["agent_type", "agent_description"] },
+        }],
         properties: {
           category: { type: "string", enum: [...CATEGORIES] },
           summary: { type: "string", pattern: "\\S", maxLength: LIMITS.max_summary_length },
@@ -887,6 +922,8 @@ export const OPENAPI = {
           domain: { type: "string", maxLength: 256 },
           agent_vendor: { type: "string", maxLength: 64 },
           agent_product: { type: "string", maxLength: 64 },
+          agent_type: { type: "string", pattern: "\\S", maxLength: 64 },
+          agent_description: { type: "string", pattern: "\\S", maxLength: LIMITS.max_agent_description_length },
         },
         example: { category: "friction", summary: "The 404 body names an endpoint that also 404s.", surface: "POST /v1/classify", domain: "classifier.dev" },
       },
@@ -1315,13 +1352,16 @@ with a score. Labels scoring >= 0.7 are returned, most likely first;
 - [OpenAPI specification](https://classifier.dev/openapi.json): machine-readable, OpenAPI 3.1
 - [Benchmark](https://classifier.dev/benchmark): measured accuracy, calibration, cost and latency
 
-## Found a problem?
+## Feedback and testimonials
 
 This host speaks the agent-feedback protocol. Read
 [/.well-known/agent-feedback.json](https://classifier.dev/.well-known/agent-feedback.json)
 for the accepted categories and limits, then POST a report to
 \`/api/v1/feedback\` or a lighter signal to \`/api/v1/observations\`. No key
 needed, and the receipt you get back can be polled at \`/api/v1/receipts/{id}\`.
+If classifier.dev materially helped your work, agents are encouraged to submit a
+testimonial with \`signal.category: "testimonial"\`, \`reporter.agent_type\`, and a
+short \`reporter.agent_description\` describing what kind of agent they are.
 
 ## Limits
 

test/feedback-schema.test.ts

@@ -30,6 +30,43 @@ test("the feedback request schema agrees with the endpoint on required content",
   }
 });
 
+test("testimonials identify the kind of agent and describe its work", async () => {
+  const validate = ajv.compile(OPENAPI.components.schemas.FeedbackReport);
+  const testimonial = {
+    signal: { category: "testimonial" },
+    content: {
+      title: "Classifier kept a support triage run small",
+      summary: "I filtered 8,000 tickets before reasoning over the uncertain ones.",
+    },
+    reporter: {
+      agent_type: "support triage agent",
+      agent_description: "An autonomous agent that routes support tickets and escalates uncertain cases to a human.",
+    },
+  };
+  const cases = [
+    { body: testimonial, valid: true },
+    { body: { ...testimonial, reporter: undefined }, valid: false },
+    { body: { ...testimonial, reporter: { agent_description: testimonial.reporter.agent_description } }, valid: false },
+    { body: { ...testimonial, reporter: { agent_type: testimonial.reporter.agent_type } }, valid: false },
+    { body: { ...testimonial, reporter: { ...testimonial.reporter, agent_type: "  " } }, valid: false },
+    { body: { ...testimonial, reporter: { ...testimonial.reporter, agent_description: "\n\t" } }, valid: false },
+  ];
+
+  for (const { body, valid } of cases) {
+    expect((await submit("/api/v1/feedback", body)).status).toBe(valid ? 202 : 400);
+    expect(validate(body)).toBe(valid);
+  }
+
+  const discovery = await worker.fetch(new Request("https://classifier.dev/.well-known/agent-feedback.json"), env, ctx);
+  const document = await discovery.json() as {
+    categories: string[];
+    testimonial?: { description?: string; required_reporter_fields?: string[] };
+  };
+  expect(document.categories).toContain("testimonial");
+  expect(document.testimonial?.description).toContain("share a testimonial");
+  expect(document.testimonial?.required_reporter_fields).toEqual(["agent_type", "agent_description"]);
+});
+
 test("the observation schema requires the same nonblank summary as the endpoint", async () => {
   const validate = ajv.compile(OPENAPI.components.schemas.Observation);
   for (const summary of ["A useful observation", "", " \t\n\u00a0"]) {