@taifoon/jev 0.2.2 → 0.2.4

package/README.md

@@ -76,6 +76,32 @@ seat. The decision is anchored on the Taifoon devnet in
 `npx @taifoon/jev run --demo` replays it from [`examples/jobs/base-bitagent-7287.recorded.json`](examples/jobs/base-bitagent-7287.recorded.json)
 with no key and no network, and arrives at the same decision digest.
 
+## In n8n
+
+The same grader runs in n8n through [`@taifoon/n8n-nodes-typesafe`](https://www.npmjs.com/package/@taifoon/n8n-nodes-typesafe),
+with eleven ready-to-import judge workflows: grade an agent's delivery, grade a Base job from its record, fact-check a
+chatbot answer, settle a refund dispute and more. See [its README](https://github.com/taifoon-io/n8n-nodes-typesafe#judge-workflows-ready-to-import).
+
+## `jev run` flags
+
+Safe by default: your own TypeSafe key only, nothing recorded, nothing signed or sent. A typo is refused, never guessed.
+
+| Flag | Default | What it does |
+|---|---|---|
+| `--demo` | off | Replays the real Base job above, offline, no key |
+| `--job <chain>:<id>` | first ready job in the layer's queue | Grade one live job, e.g. `8453:bitagent:8453:7287` |
+| `--job-file job.json` | | Grade a job you describe (see `examples/jobs/`) |
+| `--evidence pack.json` | | Grade your own evidence pack, no layer |
+| `--answers answers.json` | | Answers you already have (e.g. from the n8n node); Jev is not asked |
+| `--record none\|devnet\|base\|both` | `none` | Opt in to the unsigned calls that record the grade on chain |
+| `--layer <https url>` / `--no-layer` | `https://coord.taifoon.dev` | Where jobs and quotes are read |
+| `--protocol <name>` | from the job id | Evaluator seat: `virtuals-erc8183`, `virtuals-memo-acp`, `bitagent-erc8183`, `assurance-hook`, `judge-adapter` |
+| `--price-usdc <n>` | the job's budget | Price for the premium quote |
+| `--yes` / `--json` | ask per step / text | Run every step without asking / print the whole trace as JSON |
+
+Environment: `TYPESAFE_KEY` (your key; without it a job that needs Jev stops and says where to get one, while a job the
+code checks reject is still graded). Exit codes: `0` done, `1` a step failed, `2` a flag was refused.
+
 ## What you must know
 
 - **Code decides the facts first.** A failed check ends the job as reject, and Jev is never asked.

package/bin/jev.mjs

@@ -12,7 +12,9 @@ const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const PKG = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'));
 const args = process.argv.slice(2);
 const flag = (n) => { const i = args.indexOf(n); return i >= 0 ? args.splice(i, 2)[1] : undefined; };
-const version = flag('--version') ?? PKG.version;
+// the newest bundle shipped (a bundle is versioned on its own and rebuilt only when the workflows change)
+const BUNDLES = readdirSync(join(ROOT, 'workflows')).filter((d) => /^\d+\.\d+\.\d+$/.test(d)).sort((x, y) => x.localeCompare(y, undefined, { numeric: true }));
+const version = flag('--version') ?? BUNDLES.at(-1) ?? PKG.version;
 const network = flag('--network') ?? 'any';
 const bundle = join(ROOT, 'workflows', version);
 const die = (m) => { console.error(m); process.exit(1); };

package/bin/run.mjs

@@ -13,7 +13,7 @@
 // Keys come from the environment only: TYPESAFE_KEY (your own TypeSafe key, console.typesafe.ai) and
 // TAIFOON_RELAYER_KEY (records the answers on the layer). Neither is printed or written anywhere.
 // Output is @taifoon/term (vendored as ./term.mjs), the same rhythm as `taifoon up` and the STUDIO run log.
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
 import { createTerm } from './term.mjs';
 
@@ -35,18 +35,36 @@ function factOf(r) {
   }
 }
 
+const USAGE = 'jev run [--demo | --job <chain>:<id> | --job-file job.json | --evidence pack.json] [--answers answers.json] [--record none|devnet|base|both] [--layer <https url> | --no-layer] [--protocol <name>] [--price-usdc <n>] [--yes] [--json]';
+const PROTOCOLS = ['assurance-hook', 'judge-adapter', 'virtuals-erc8183', 'virtuals-memo-acp', 'bitagent-erc8183'];
+/** A stranger's typo must never run something else: every flag is known, every value checked, exit 2 with the fix. */
+function refuse(msg) { process.stderr.write(`jev run: ${msg}\n  ${USAGE}\n`); process.exit(2); }
+
 export async function run(argv) {
   const a = [...argv];
   const has = (n) => { const i = a.indexOf(n); if (i < 0) return false; a.splice(i, 1); return true; };
-  const val = (n) => { const i = a.indexOf(n); return i >= 0 ? a.splice(i, 2)[1] : undefined; };
+  const val = (n) => {
+    const i = a.indexOf(n); if (i < 0) return undefined;
+    const v = a[i + 1]; if (v === undefined || v.startsWith('--')) refuse(`${n} needs a value`);
+    a.splice(i, 2); return v;
+  };
+  const file = (n) => { const f = val(n); if (f !== undefined && !existsSync(f)) refuse(`${n}: no such file ${f}`); return f; };
   const yes = has('--yes') || !process.stdin.isTTY; const json = has('--json'); const noLayer = has('--no-layer') || argv.includes('--demo') || argv.includes('--job-file');
   const demo = has('--demo');
-  const job = val('--job'); const evFile = val('--evidence');
-  const jobFile = val('--job-file');
-  const ansFile = val('--answers');
+  const job = val('--job'); const evFile = file('--evidence');
+  const jobFile = file('--job-file');
+  const ansFile = file('--answers');
   const rec = demo ? JSON.parse(readFileSync(new URL('../examples/jobs/base-bitagent-7287.recorded.json', import.meta.url), 'utf8')) : null;
   const network = val('--record') ?? val('--network') ?? 'none'; const layer = noLayer ? false : val('--layer');
   const protocol = val('--protocol'); const price = val('--price-usdc');
+  if (a.length) refuse(`unknown flag ${a[0]}`);
+  if (!['none', 'devnet', 'base', 'both'].includes(network)) refuse(`--record is none, devnet, base or both (got ${network})`);
+  if (demo && (job || evFile || jobFile || ansFile)) refuse('--demo replays one recorded job: drop --job, --job-file, --evidence and --answers');
+  if ([job, evFile, jobFile].filter(Boolean).length > 1) refuse('pick one source: --job, --job-file or --evidence');
+  if (job && !/^\d+:.+$/.test(job) && !/^\S+$/.test(job)) refuse(`--job is <chain>:<id>, e.g. 8453:bitagent:8453:7287 (got ${job})`);
+  if (layer && !/^https:\/\//.test(layer)) refuse('--layer must be an https:// URL');
+  if (protocol && !PROTOCOLS.includes(protocol)) refuse(`--protocol is one of ${PROTOCOLS.join(', ')}`);
+  if (price !== undefined && !(Number(price) > 0)) refuse(`--price-usdc must be a positive number (got ${price})`);
   const { pipeline, STEPS, prepareJob } = await import('../dist/index.js');
 
   const t = createTerm({ quiet: json });

package/dist/pipeline.js

@@ -142,9 +142,15 @@ export async function pipeline(o = {}) {
         }
         else if (o.key)
             g.key = o.key;
-        else
-            throw new Error('Jev needs your TypeSafe key: set TYPESAFE_KEY (console.typesafe.ai), or pass answers you already have');
-        t.receipt = await grade(g);
+        // no key: a job the code checks reject is still graded (Jev is not asked); only asking Jev needs the key
+        try {
+            t.receipt = await grade(g);
+        }
+        catch (e) {
+            if (!o.key && !o.answers && /TypeSafe key/.test(e.message))
+                throw new Error('Jev needs your TypeSafe key: set TYPESAFE_KEY (console.typesafe.ai), or pass answers you already have');
+            throw e;
+        }
         return { verdict: t.receipt.verdict, reasons: t.receipt.reasons, model: t.receipt.model, receiptHash: t.receipt.receiptHash };
     });
     if (failed() || !t.receipt)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taifoon/jev",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Grade AI agent jobs with TypeSafe's Jev and record the verdict on chain: code checks the facts, Jev answers a published rubric, and you get a receipt, the on-chain record and the evaluator call for ERC-8183 and Virtuals ACP. No runtime dependencies, no key inside.",
   "keywords": [
     "jev",
@@ -60,7 +60,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit -p .",
     "test": "vitest run",
-    "check": "npm run typecheck && npm test && npm run build",
+    "check": "npm run typecheck && npm run build && npm test",
     "prepublishOnly": "npm run check",
     "bundle": "node scripts/bundle-workflows.mjs",
     "zip": "node scripts/zip-workflows.mjs"