@muretai/agent-entry 1.9.0 → 1.11.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muretai/agent-entry",
-  "version": "1.9.0",
-  "description": "Make your website answer AI agents: an A2A agent endpoint that verifies who is knocking, opens an account for them and replies signed, in one HTTP round trip. Zero dependencies. Pairs with llms.txt and WebMCP.",
+  "version": "1.11.0",
+  "description": "Agents already visit your site. Give them a way to become a customer: know who knocked, remember them next time, answer in the same request. Zero dependencies.",
   "type": "module",
   "main": "muretai-agent-entry.mjs",
   "exports": {
@@ -11,6 +11,8 @@
     "muretai-agent-entry.mjs",
     "conformance/",
     "examples/server.mjs",
+    "diagrams/",
+    "scripts/distill/",
     "LICENSE",
     "spec/",
     "README.md"
@@ -20,7 +22,10 @@
   },
   "scripts": {
     "test": "node conformance/run.mjs",
-    "example": "node examples/server.mjs"
+    "example": "node examples/server.mjs",
+    "distill": "node scripts/distill/loop.mjs",
+    "distill:record": "node scripts/distill/record.mjs",
+    "distill:measure": "node scripts/distill/measure.mjs"
   },
   "keywords": [
     "ai-agent",

package/scripts/distill/README.md

@@ -0,0 +1,32 @@
+# Local feedback loop (this machine only)
+
+Turn knocks you already answered into a **proposed** `skills[]` menu, and
+measure whether that menu would have made the next visitor’s first knock
+useful.
+
+Nothing here uploads visitor text, DIDs, or traces. The Distiller is not
+imported by `muretai-agent-entry.mjs`.
+
+```
+npm run distill              # fixtures → skills.json → holdout measure
+npm run distill -- --m0      # also run the door conformance suite
+npm run distill:record       # print the observer snippet
+```
+
+## Record (optional)
+
+`createAgentEntry({ observer: fileSink() })` appends POST outcomes to
+`var/traces.jsonl` (gitignored). Card/notice GETs are dropped. DIDs are
+not written. The door still discards the observer’s return — a full disk
+cannot change a signed reply.
+
+## Admission
+
+Publish the proposed menu onto *your* card only when:
+
+1. holdout first-knock useful rises
+2. emptying the Distiller kills that lift
+3. every proposed `examples[]` entry is answerable by *your* responder
+4. the door conformance suite is still green
+
+This package never patches a stranger’s `skills[]`.

package/scripts/distill/distill.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Traces → generated/skills.json + rules.json.
+ * Empty Distiller: --empty (mutation). Never writes the running card.
+ */
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inferRules, loadCases, proposedSkills, readJsonl, tracesFromCases, respond } from './lib.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '../..');
+const OUT = resolve(ROOT, 'generated');
+
+function localTraces(path) {
+  return readJsonl(path).map((row, i) => {
+    const text = row.text || row.doc?.text || '';
+    const env = respond(text);
+    return {
+      id: row.id || `local-${i + 1}`,
+      intent: /\b(book|reserve|slot)\b/i.test(text) ? 'book' : (/\b(price|cost|how much)\b/i.test(text) ? 'price' : 'other'),
+      text,
+      tag: env.tag,
+      environment_useful: env.useful,
+    };
+  });
+}
+
+const empty = process.argv.includes('--empty');
+const tracesPath = process.env.AE_TRACES || resolve(ROOT, 'var/traces.jsonl');
+const train = tracesFromCases(loadCases(), 'train');
+const local = existsSync(tracesPath) ? localTraces(tracesPath) : [];
+const rules = empty ? { empty: true, examples: [], evidence: [] } : inferRules([...train, ...local]);
+const skills = proposedSkills(rules);
+
+mkdirSync(OUT, { recursive: true });
+writeFileSync(resolve(OUT, 'rules.json'), JSON.stringify(rules, null, 2) + '\n');
+writeFileSync(resolve(OUT, 'skills.json'), JSON.stringify(skills, null, 2) + '\n');
+writeFileSync(resolve(OUT, 'R.json'), JSON.stringify({
+  traces: train.length + local.length,
+  local: local.length,
+  empty,
+  book_require_day: Boolean(rules.book_require_day),
+  examples: rules.examples || [],
+}, null, 2) + '\n');
+
+process.stdout.write(
+  `distilled ${train.length} fixture + ${local.length} local traces`
+  + (empty ? ' (empty Distiller)' : '')
+  + ` → generated/skills.json (${skills.length} skill(s))\n`,
+);

package/scripts/distill/fixtures.json

@@ -0,0 +1,10 @@
+{
+  "comment": "First dojo: a booking desk that cannot answer a book request without a day. Gold is the fixture responder (same policy as examples/server.mjs). Placeholders only.",
+  "cases": [
+    { "id": "book-no-day", "split": "train", "intent": "book", "naive_text": "I want to book a shoot" },
+    { "id": "book-saturday", "split": "train", "intent": "book", "naive_text": "Book Saturday 14:00" },
+    { "id": "price", "split": "train", "intent": "price", "naive_text": "What does a 60-minute shoot cost?" },
+    { "id": "book-holdout", "split": "holdout", "intent": "book", "naive_text": "Can I reserve a session" },
+    { "id": "price-holdout", "split": "holdout", "intent": "price", "naive_text": "How much is a half-day?" }
+  ]
+}

package/scripts/distill/lib.mjs

@@ -0,0 +1,100 @@
+/**
+ * Local AE distill helpers. The Distiller never imports the door runtime.
+ * Gold labels come from the fixture responder (the same policy the example
+ * studio already implements: a book request without a day is not yet useful).
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DAY = /\b(mon|tue|wed|thu|fri|sat|sun|monday|tuesday|wednesday|thursday|friday|saturday|sunday|20\d{2}-\d{2}-\d{2})\b/i;
+const PRICE = /\b(price|cost|how much|jpy|half-day|60-minute)\b/i;
+
+export function loadCases() {
+  return JSON.parse(readFileSync(join(HERE, 'fixtures.json'), 'utf8')).cases;
+}
+
+/** Environment: what this desk actually answers. */
+export function respond(text) {
+  const t = String(text || '');
+  if (PRICE.test(t)) {
+    return { tag: 'price', useful: true, text: 'A 60-minute shoot is 12000 JPY, two people included.' };
+  }
+  if (DAY.test(t)) {
+    return { tag: 'open', useful: true, text: 'Saturday 14:00 is open. 12000 JPY for a 60-minute shoot.' };
+  }
+  return { tag: 'ask_day', useful: false, text: 'Which day? Name a weekday or YYYY-MM-DD.' };
+}
+
+export function naiveText(case_) {
+  return case_.naive_text;
+}
+
+export function inferRules(traces) {
+  const rules = {
+    empty: traces.length === 0,
+    book_require_day: false,
+    examples: [],
+    evidence: [],
+  };
+  for (const tr of traces) {
+    rules.evidence.push({ id: tr.id, intent: tr.intent, useful: tr.environment_useful, tag: tr.tag });
+    if (tr.intent === 'book' && !tr.environment_useful && tr.tag === 'ask_day') {
+      rules.book_require_day = true;
+    }
+    if (tr.environment_useful && tr.intent === 'book' && DAY.test(tr.text)) {
+      rules.examples.push(tr.text);
+    }
+    if (tr.environment_useful && tr.intent === 'price') {
+      rules.examples.push(tr.text);
+    }
+  }
+  rules.examples = [...new Set(rules.examples)];
+  return rules;
+}
+
+export function applyText(case_, rules) {
+  if (rules.empty) return naiveText(case_);
+  let text = naiveText(case_);
+  if (rules.book_require_day && case_.intent === 'book' && !DAY.test(text)) {
+    const ex = rules.examples.find((e) => DAY.test(e));
+    text = ex || `${text} Saturday`;
+  }
+  return text;
+}
+
+export function tracesFromCases(cases, split = 'train') {
+  return cases.filter((c) => c.split === split).map((c) => {
+    const text = naiveText(c);
+    const env = respond(text);
+    return {
+      id: c.id,
+      intent: c.intent,
+      text,
+      tag: env.tag,
+      environment_useful: env.useful,
+    };
+  });
+}
+
+export function proposedSkills(rules) {
+  if (rules.empty) return [];
+  const examples = rules.examples.length
+    ? rules.examples
+    : (rules.book_require_day ? ['Book Saturday 14:00'] : []);
+  return [{
+    id: 'ask',
+    name: 'signed-answers-about-the-studio',
+    description: rules.book_require_day
+      ? 'Ask what a shoot costs, and book by naming a day. The answer comes back signed.'
+      : 'Ask what a shoot costs and how to book. The answer comes back signed.',
+    tags: ['studio', 'booking', 'signed', 'inline-reply'],
+    examples,
+  }];
+}
+
+export function readJsonl(path) {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
+}

package/scripts/distill/loop.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Local loop: distill fixtures (+ optional var/traces.jsonl) → measure → mutation.
+ * --m0 also runs the door conformance suite. Never uploads. Never edits the card.
+ */
+import { spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '../..');
+const runM0 = process.argv.includes('--m0');
+
+function run(file, extra = []) {
+  const r = spawnSync(process.execPath, [resolve(HERE, file), ...extra], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (r.stdout) process.stdout.write(r.stdout);
+  if (r.stderr) process.stderr.write(r.stderr);
+  if (r.status !== 0) process.exit(r.status ?? 1);
+}
+
+run('distill.mjs');
+run('measure.mjs');
+process.stdout.write('\n--- mutation (empty Distiller) ---\n');
+run('distill.mjs', ['--empty']);
+run('measure.mjs', ['--empty']);
+run('distill.mjs');
+
+const unit = spawnSync(process.execPath, ['--test', resolve(HERE, 'test.mjs')], {
+  cwd: ROOT,
+  encoding: 'utf8',
+});
+if (unit.stdout) process.stdout.write(unit.stdout);
+if (unit.stderr) process.stderr.write(unit.stderr);
+if (unit.status !== 0) process.exit(unit.status ?? 1);
+
+if (runM0) {
+  process.stdout.write('\n--- M0 npm test (conformance) ---\n');
+  const t = spawnSync('npm', ['test'], { cwd: ROOT, encoding: 'utf8' });
+  if (t.stdout) process.stdout.write(t.stdout);
+  if (t.stderr) process.stderr.write(t.stderr);
+  if (t.status !== 0) process.exit(t.status ?? 1);
+}

package/scripts/distill/measure.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * M2: held-out visitor prompts. Naive sends the prompt as-is.
+ * Skill rewrites a book request that names no day using a distilled example.
+ * Gold = fixture responder. Mutation: --empty → apply == naive, lift 0.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { applyText, loadCases, naiveText, respond } from './lib.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '../..');
+const OUT = resolve(ROOT, 'generated');
+
+function loadRules(empty) {
+  if (empty) return { empty: true, examples: [] };
+  const p = resolve(OUT, 'rules.json');
+  if (!existsSync(p)) {
+    process.stderr.write('measure.mjs: run distill.mjs first (no generated/rules.json)\n');
+    process.exit(1);
+  }
+  return JSON.parse(readFileSync(p, 'utf8'));
+}
+
+function score(cases, textOf) {
+  const rows = [];
+  let ok = 0;
+  for (const c of cases) {
+    const text = textOf(c);
+    const env = respond(text);
+    if (env.useful) ok += 1;
+    rows.push({ id: c.id, intent: c.intent, text, useful: env.useful, tag: env.tag });
+  }
+  return { ok, n: cases.length, pct: cases.length ? ok / cases.length : 0, rows };
+}
+
+const empty = process.argv.includes('--empty');
+const rules = loadRules(empty);
+const holdout = loadCases().filter((c) => c.split === 'holdout');
+const without = score(holdout, naiveText);
+const withSkill = score(holdout, (c) => applyText(c, rules));
+const lift = withSkill.pct - without.pct;
+
+const lines = [
+  '# Agent Entry — local distill measure',
+  '',
+  empty ? 'Arm: **empty Distiller** (mutation).' : 'Arm: distilled `generated/rules.json`.',
+  '',
+  `| arm | holdout first-knock useful |`,
+  `|---|---|`,
+  `| without skill (send the prompt) | ${without.ok}/${without.n} (${(without.pct * 100).toFixed(0)}%) |`,
+  `| with skill | ${withSkill.ok}/${withSkill.n} (${(withSkill.pct * 100).toFixed(0)}%) |`,
+  `| lift | ${(lift * 100).toFixed(0)} pt |`,
+  '',
+  'Gold is the fixture responder, not a transcript judge.',
+  '',
+  '### holdout',
+  '',
+  ...withSkill.rows.map((r) => {
+    const w = without.rows.find((x) => x.id === r.id);
+    return `- \`${r.id}\` naive="${w.text}" → ${w.tag} | skill="${r.text}" → ${r.tag} ${r.useful ? 'ok' : 'MISS'}`;
+  }),
+  '',
+  'Proposed menu: generated/skills.json — not written onto the running card.',
+  '',
+];
+
+mkdirSync(OUT, { recursive: true });
+writeFileSync(resolve(OUT, 'report.md'), lines.join('\n'));
+process.stdout.write(lines.join('\n'));
+
+if (empty && lift !== 0) {
+  process.stderr.write('mutation failed: empty Distiller still produced lift\n');
+  process.exit(2);
+}
+if (!empty && lift <= 0) {
+  process.stderr.write('no lift on holdout — do not publish the proposed skills[]\n');
+  process.exit(2);
+}

package/scripts/distill/record.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Owner-local observer sink. Writes to a path on THIS machine. Never uploads.
+ *
+ * Wire it when you construct the door:
+ *
+ *   import { fileSink } from './scripts/distill/record.mjs';
+ *   createAgentEntry({ ..., observer: fileSink() });
+ *
+ * CLI: print the snippet, or append a JSON row from stdin.
+ *
+ *   node scripts/distill/record.mjs
+ *   node scripts/distill/record.mjs --file var/traces.jsonl --stdin < row.json
+ */
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '../..');
+
+export function defaultTracePath() {
+  return process.env.AE_TRACES || resolve(ROOT, 'var/traces.jsonl');
+}
+
+/**
+ * Observer that cannot change a verdict (the door already discards its return).
+ * Drops card/notice GETs. Never writes a DID.
+ */
+export function fileSink(path = defaultTracePath()) {
+  return (env) => {
+    try {
+      if (!env || env.stage === 'card_get' || env.stage === 'notice_get') return;
+      const row = {
+        ts: new Date().toISOString(),
+        text: typeof env.text === 'string' ? env.text : '',
+        verified: Boolean(env.verified),
+        stage: env.stage || null,
+        refuse_code: env.refuse_code ?? null,
+      };
+      mkdirSync(dirname(path), { recursive: true });
+      appendFileSync(path, JSON.stringify(row) + '\n');
+    } catch {
+      // Observer contract: a throw is swallowed by the door; we swallow here too.
+    }
+  };
+}
+
+function usage(code = 0) {
+  process.stdout.write(
+    'Local AE traces — this machine only, never uploaded.\n'
+    + '\n'
+    + '  import { fileSink } from \'./scripts/distill/record.mjs\';\n'
+    + '  createAgentEntry({ seedHex, name, baseUrl, responder, observer: fileSink() });\n'
+    + '\n'
+    + '  node scripts/distill/record.mjs --stdin < row.json\n'
+    + `  default file: ${defaultTracePath()}\n`,
+  );
+  process.exit(code);
+}
+
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('record.mjs')) {
+  const argv = process.argv.slice(2);
+  if (!argv.length || argv.includes('--help') || argv.includes('-h')) usage(0);
+  let file = defaultTracePath();
+  let stdin = false;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--file') { file = resolve(argv[++i] || ''); continue; }
+    if (argv[i] === '--stdin') { stdin = true; continue; }
+    usage(1);
+  }
+  if (!stdin) usage(1);
+  const raw = readFileSync(0, 'utf8');
+  if (!raw.trim()) {
+    process.stderr.write('record.mjs: stdin is empty\n');
+    process.exit(1);
+  }
+  let doc;
+  try { doc = JSON.parse(raw); } catch (e) {
+    process.stderr.write(`record.mjs: stdin is not JSON: ${e.message}\n`);
+    process.exit(1);
+  }
+  fileSink(file)({
+    text: doc.text || '',
+    verified: Boolean(doc.verified),
+    stage: doc.stage || 'signed_post',
+    refuse_code: doc.refuse_code ?? null,
+  });
+  process.stdout.write(`recorded 1 row → ${file}\n`);
+}

package/scripts/distill/test.mjs

@@ -0,0 +1,43 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { applyText, inferRules, loadCases, naiveText, proposedSkills, respond, tracesFromCases } from './lib.mjs';
+
+function score(cases, textOf) {
+  let ok = 0;
+  for (const c of cases) {
+    if (respond(textOf(c)).useful) ok += 1;
+  }
+  return cases.length ? ok / cases.length : 0;
+}
+
+test('responder asks for a day when the book prompt names none', () => {
+  assert.equal(respond('I want to book a shoot').useful, false);
+  assert.equal(respond('I want to book a shoot').tag, 'ask_day');
+  assert.equal(respond('Book Saturday 14:00').useful, true);
+});
+
+test('distilled menu beats sending the prompt as-is on holdout', () => {
+  const cases = loadCases();
+  const rules = inferRules(tracesFromCases(cases, 'train'));
+  const holdout = cases.filter((c) => c.split === 'holdout');
+  const without = score(holdout, naiveText);
+  const withSkill = score(holdout, (c) => applyText(c, rules));
+  assert.ok(withSkill > without, `expected lift, got without=${without} with=${withSkill}`);
+  assert.equal(withSkill, 1);
+});
+
+test('empty Distiller produces no lift (producer mutation)', () => {
+  const holdout = loadCases().filter((c) => c.split === 'holdout');
+  const without = score(holdout, naiveText);
+  const withEmpty = score(holdout, (c) => applyText(c, { empty: true }));
+  assert.equal(withEmpty, without);
+});
+
+test('proposed skills[] examples are answerable by the responder', () => {
+  const rules = inferRules(tracesFromCases(loadCases(), 'train'));
+  const skills = proposedSkills(rules);
+  assert.ok(skills.length >= 1);
+  for (const ex of skills[0].examples) {
+    assert.equal(respond(ex).useful, true, `example not answerable: ${ex}`);
+  }
+});