@muretai/agent-entry 1.10.0 → 1.11.0

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}`);
+  }
+});

package/spec/skill-distill.md

@@ -0,0 +1,219 @@
+# Agent Entry — Episode-to-Skill (site side)
+
+Status: **local loop shipped** (`scripts/distill/`). Does not change the v1
+HTTP contract (`spec/v1.md`).
+Method: Repo-To-Skill (arXiv 2609.02749) — distill, verify, load only what
+the task needs. Source: outcome-labeled knocks at **this** door, not a
+GitHub crawl and not a network-wide catalog.
+
+This repository stays the door. Distillation is an **owner-side, offline**
+loop. Nothing here is added to `muretai-agent-entry.mjs` at request time.
+
+---
+
+## 1. What is missing today
+
+A visiting agent reads the card before it knocks. If `skills[]` is empty or
+wrong, it guesses and learns the menu from refusals. The README already
+states the two owner duties:
+
+- every `examples[]` entry must be answerable by the responder
+- declare only what the responder actually does
+
+Those duties are still hand-written. The paper's claim is that this
+operating knowledge already exists in **grounded outcomes** — signed
+envelopes plus what the door did — and can be distilled into the menu the
+next visitor sees.
+
+The door already emits the labels, without changing a verdict:
+
+- `observer(env)` runs **after** the reply; its return is discarded
+- `stats()` / `clientStats()` count family and stage, including refusals
+- JSON-RPC refusals teach (`-32004` over-rate, unsigned, replay, wrong
+  recipient); the recipe already rides in the refusal
+- the responder's own result (answered / asked for a missing field /
+  handed off) is the site-specific outcome
+
+User-Agent never affects `verified`, a ledger row, a rate lane, or any
+refusal. Distillation must not reopen that. UA is a counting hint, not a
+training label for "who to trust".
+
+---
+
+## 2. What to steal, what to refuse
+
+Steal: four-stage distillation (scope → ground → construct → verify);
+skills as operating context, not a new control loop; environment-grounded
+admission (a transcript-only gate cannot improve uniformly); withhold-the-
+skill measurement.
+
+Refuse:
+
+- Distiller inside the one-file runtime (zero dependencies, no database)
+- a hosted catalog of every site's skills
+- FOLLOW of visitor-authored text (`env.text` stays untrusted data)
+- stamping a third-party `howToUrl` (empty means omitted; only a URL the
+  owner operates)
+- changing any wire byte or verdict because a skill exists
+
+---
+
+## 3. Mapping
+
+| Paper | This repo |
+|---|---|
+| Declarative source | Signed inbound `text` + door outcome (verify / refuse code / responder result) |
+| Skill | A2A `skills[]` on the **signed** card; optional owner `howToUrl`; optional `SKILL.md` the owner hosts |
+| Skill graph | One entry skill (what this door answers) → component skills per declared capability |
+| Router | The card itself. Visitors read `skills[]` before POST. Agent Web Router finds the door; it does not write this menu |
+| Verification | Card signature still covers the menu. Examples are driven through the responder in tests (already required) |
+| Creator / researcher | Owner Distiller writes a proposed menu; the running entry only **serves** what the owner published |
+
+```
+visitor  --probe-->  card.skills[]  (menu; signed)
+visitor  --knock-->  POST door      (unchanged contract)
+observer --trace-->  local log      (after verdict)
+Distiller (offline) --> proposed skills[] / how-to
+owner publishes --> card resigns
+```
+
+---
+
+## 4. Distiller pipeline (offline, this repo or a sibling package)
+
+Anchor is this origin's door, not a task on the open web.
+
+1. **Scope.** One capability the responder already implements (hours,
+   quote, book, …). Do not invent a skill the responder cannot keep.
+2. **Ground.** Read owner-local traces only: `observer` rows the owner
+   chose to keep, plus the door's refuse reason. A row is
+   `{text, verified, refuse_code?, responder_tag, ts}`. No operator
+   aggregation across sites.
+3. **Construct.** Propose:
+   - `skills[]` id / name / description / tags / **answerable** examples
+   - optional how-to prose at a URL the owner operates
+   - construction record `R`: evidence (trace ids), checks, remaining gaps
+4. **Verify (M0).** Before publish:
+   - the new card still signs
+   - every example POSTed to the local entry gets a signed reply the
+     visitor could accept (existing "examples are promises" rule)
+   - refuse rate on a frozen visitor suite does not rise
+   - remaining gaps stay in `R`
+
+The running entry never imports the Distiller. Shipped layout (not
+imported by the one-file runtime):
+
+```
+scripts/distill/          # owner CLI
+  record.mjs              # fileSink() for observer → var/traces.jsonl
+  distill.mjs             # traces → generated/skills.json
+  measure.mjs             # M2 with/without the proposed menu
+  loop.mjs                # distill → measure → mutation
+```
+
+`npm run distill`. Proposed `skills[]` is never written onto the running
+card. `--m0` also runs the door conformance suite.
+
+`createAgentEntry({ observer })` already exists. Recording is an owner
+choice. Default remains no disk.
+
+---
+
+## 5. Measurement
+
+A skill cannot be graded by reading it (ACES, arXiv 2608.20614).
+
+- **M0 admission** — signed card; examples answerable; contract suite
+  (`conformance/`) still green. Fail-closed.
+- **M2 lift** — freeze responder, rates, and a held-out visitor prompt
+  set. Arm A: current `skills[]` / how-to. Arm B: proposed menu. Score
+  only what a visitor observes: first-knock useful answer, refuse-for-
+  missing-field, handoff that the card still names. Not token count.
+- **Producer mutation** — Distiller emits empty `skills[]`. Lift must
+  fall to ~0. If it stays green, the test was scoring the responder.
+- **No leaderboard.** One site, that site's traces, that site's reader.
+
+Publish rule: M0 holds, M2 first-knock success rises or refuse-for-guess
+falls, mutation kills the lift.
+
+---
+
+## 6. First dojo (this repo, no production traffic)
+
+Frozen visitor prompts against `examples/server.mjs` (or a fixture
+responder) that requires a missing field the naive visitor omits.
+
+- Train traces: naive knocks that the responder rejects with a teachable
+  reason, plus one complete knock.
+- Distiller writes a skill example that includes the field.
+- Holdout: a new wording of the same need.
+- Naive visitor still omits the field; skill-equipped visitor includes it.
+- Mutation: empty Distiller, both arms omit, lift 0.
+
+Do not use live `muretai.com` traffic for the first number.
+
+---
+
+## 7. What this does not change
+
+v1 HTTP surface, Ed25519 envelope, account-from-first-signature, rate
+lanes, Web Bot Auth as recognition-only, `Link` signpost, path mounts,
+`domains`. Agent Web Router remains a **visitor** of this door. It may
+read the distilled menu; it must not write it.
+
+## 8. Relation to `muretai-skill-distill`
+
+That sibling app proved withhold-the-skill lift on a fail-closed parse
+dojo. This design is the same method with a different source: **door
+outcomes**, not `x-rlds` lines. Do not vendor-copy core crypto. The entry
+already verifies signatures.
+
+---
+
+## 9. Live loop — two rails (we never see installer traffic)
+
+This package is installed by other people, on origins we do not operate.
+Their visitors' messages, accounts, and `observer` rows are **not ours**
+and MUST NOT be fetched, phoned home, or scraped. There is no telemetry
+channel. Evolution therefore splits.
+
+### Rail A — this package (what we can update)
+
+We improve the **door machinery and the refusal recipe**, not a site's
+menu. Labels come only from sources we already own or that someone
+chose to publish:
+
+- `conformance/` vectors and the contract suite (attacks we author)
+- the doors **we** run (for example the muretai.com entry)
+- a GitHub issue a site owner **opts into**, attaching a redacted
+  fixture they exported (`export --redact` if later built; default off,
+  never runs itself)
+
+A package release may change refusal text, `howTo` defaults (still no
+third-party host), rate-lane behaviour, or new contract tests. It MUST
+NOT patch a stranger's `skills[]`. That list is their signed claim.
+
+Measure a release against **our** fixtures (§5). If we do not have a
+new fixture, we do not have a new skill.
+
+### Rail B — each installer's machine (what they can update)
+
+The only place their knock data exists is their process. The Distiller,
+if they run it, reads a local `observer` sink they configured. The
+child `skills[]` stays on their card. We never receive it.
+
+```
+their observer → their disk → their Distiller → their next card
+```
+
+`stats()` they already have is for **them**. It is not a feed to us.
+User-Agent remains unusable as a label.
+
+### What we do when we cannot see production
+
+We do not wait for it. The first dojo (§6) and every later package
+change are fixture-grown. When a user reports "visitors keep getting
+refused and the recipe did not teach X", the artifact we want is a
+**reproducing envelope**, not their ledger. That becomes a conformance
+case. That is the only upstream ratchet that does not take their
+customers.