@taifoon/jev 0.2.17 → 0.2.18

package/README.md

@@ -14,7 +14,8 @@ npx @taifoon/jev run --demo
 
 ![npx @taifoon/jev run --demo: a BitAgent job on Base, graded by Jev, checked against the chain](https://raw.githubusercontent.com/taifoon-io/jev/main/docs/demo.gif)
 
-Then grade your own with your TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai). Installing it also
+Then grade your own: with no key, on your free grades on the Taifoon coordination layer (3 a day per caller), or with
+your TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai). Installing it also
 installs Taifoon's other packages (@taifoon/jev-wilson, @taifoon/n8n-nodes-typesafe). No key inside, and it signs nothing. Recording a grade on chain is optional.
 
 ## Quick start
@@ -55,7 +56,7 @@ claims the evidence cannot support. Grade one with your key:
 ```
 TYPESAFE_KEY=… npx @taifoon/jev run --job-file examples/jobs/invoice-extraction.json
 npx @taifoon/jev run --demo      # offline, no key: replays the Base job below and checks it against the chain
-npx @taifoon/jev run             # a live Base job from the coordination layer's queue (needs TYPESAFE_KEY)
+npx @taifoon/jev run             # a live Base job from the coordination layer's queue (your TYPESAFE_KEY, else the free grades)
 ```
 
 ## A Base job, graded
@@ -121,8 +122,9 @@ Safe by default: your own TypeSafe key only, nothing recorded, nothing signed or
 | `--seller-record <k>/<n>` | read from the layer | Price the premium here from the seller's record (k delivered of n graded) with [`@taifoon/jev-wilson`](https://www.npmjs.com/package/@taifoon/jev-wilson): the layer's numbers, no request |
 | `--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.
+Environment: `TYPESAFE_KEY` (your key; without it a job that needs Jev is graded on your free grades on the layer, and
+past them it stops and says how to pay one grade; a job the code checks reject is graded either way; `--no-layer`, `--demo` and `--job-file` ask
+no one). `TAIFOON_RELAYER_KEY` pays layer grades past the free ones from that key's balance. Exit codes: `0` done, `1` a step failed, `2` a flag was refused.
 
 ## What you must know
 
@@ -132,8 +134,12 @@ code checks reject is still graded). Exit codes: `0` done, `1` a step failed, `2
 - **Code composes the verdict** under THRESHOLDS_v1: complete, reject or needs_review. needs_review ends nothing and
   leaves room for an appeal. Above 50 USDC a complete is held for review.
 - **Nothing is signed.** `record()` and `evaluatorCall()` return unsigned calls. Whoever holds the seat signs.
-- **Your key.** Jev is called with your own TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai),
-  directly at TypeSafe. The key is not stored and never appears in a receipt.
+- **Your key, or the free grades.** With your own TypeSafe key from [console.typesafe.ai](https://console.typesafe.ai),
+  Jev is called directly at TypeSafe; the key is not stored and never appears in a receipt. Without one, `grade()`
+  claims one of your free grades on the coordination layer (`POST https://coord.taifoon.dev/v1/judge/compose`, 3 a day
+  per caller): the layer asks Jev the same four questions and this package composes the verdict from the answers, so the
+  receipt is the same shape (`via.connection: "trial"`, with the grades left). Past them the layer answers 402 with the
+  price of one grade (x402), or pass `layerKey` (a Taifoon key) to pay from its balance. `layer: false` turns this off.
 - **What the result is.** *Graded against a published rubric by a pinned decision model, with an appeal.* It is not
   "independently verified". An on-chain record is an attestation by whoever sent it, not a proof the answer is right.
 
@@ -211,4 +217,4 @@ In code: `verify(digest, { network: 'arbitrum' })` (a name or a chain id), `{ rp
 
 Independent project. Jev and TypeSafe are products of TypeSafe AI, Inc., which does not endorse this package.
 
-Built by Taifoon. MIT. Its runtime dependencies are Taifoon's own packages, @taifoon/jev-wilson (the pricing) and @taifoon/n8n-nodes-typesafe; nothing third-party. It contains no key. It calls Jev only with your own TypeSafe key.
+Built by Taifoon. MIT. Its runtime dependencies are Taifoon's own packages, @taifoon/jev-wilson (the pricing) and @taifoon/n8n-nodes-typesafe; nothing third-party. It contains no key. It calls Jev with your own TypeSafe key, or without one through your free grades on the Taifoon coordination layer.

package/bin/run.mjs

@@ -1,5 +1,5 @@
 // jev run — one job through the pipeline, one step at a time.
-//   jev run                              the first ready job on the coordination layer's queue (needs TYPESAFE_KEY)
+//   jev run                              the first ready job on the coordination layer's queue (your TYPESAFE_KEY, else the free grades)
 //   jev run --job 8453:81100             a job you name (chain:id; ids like bitagent:8453:7287 work too)
 //   jev run --evidence pack.json         your own pack, no layer at all: { subject, state, delivered?, checks?, priceUsdc? }
 //   jev run --job-file job.json          one agent job: { id, task, criteria[], delivered, source?, checks[] } (see examples/jobs/)
@@ -71,7 +71,7 @@ export async function run(argv) {
 
   const t = createTerm({ quiet: json });
   const rl = yes ? null : createInterface({ input: process.stdin, output: process.stdout });
-  t.info(`jev run · ${noLayer ? 'offline' : `layer ${layer ?? 'https://coord.taifoon.dev'}`} · grade on ${demo ? `Jev's recorded answers for ${rec.job.ref} (${rec.job.task})` : ansFile ? 'supplied answers' : process.env.TYPESAFE_KEY ? 'your TypeSafe key' : 'no key: set TYPESAFE_KEY, or try --demo'} · record → ${network === 'none' ? 'none (opt in with --record devnet|base|both)' : network}${process.env.TAIFOON_RELAYER_KEY ? ' + the layer' : ''}`);
+  t.info(`jev run · ${noLayer ? 'offline' : `layer ${layer ?? 'https://coord.taifoon.dev'}`} · grade on ${demo ? `Jev's recorded answers for ${rec.job.ref} (${rec.job.task})` : ansFile ? 'supplied answers' : process.env.TYPESAFE_KEY ? 'your TypeSafe key' : noLayer ? 'no key: set TYPESAFE_KEY, or try --demo' : 'your free grades on the layer (no TypeSafe key)'} · record → ${network === 'none' ? 'none (opt in with --record devnet|base|both)' : network}${process.env.TAIFOON_RELAYER_KEY ? ' + the layer' : ''}`);
 
   const trace = await pipeline({
     layer, job, network, protocol, priceUsdc: price ? Number(price) : undefined, sellerRecord: recM ? { k: Number(recM[1]), n: Number(recM[2]) } : undefined,

package/dist/ask.d.ts

@@ -6,9 +6,16 @@ export type Asked = {
     answers: Record<string, Answer>;
     model: string | null;
     latency_ms: number | null;
-    connection: 'key';
-    trial: null;
+    connection: 'key' | 'trial';
+    trial: {
+        calls: number;
+        left: number;
+    } | null;
 };
+/** the coordination layer, where a caller without a TypeSafe key claims its free grades */
+export declare const LAYER_URL = "https://coord.taifoon.dev";
+/** the questions the layer's free grade answers (RUBRIC_v1 asks exactly these); another rubric needs the caller's own key */
+export declare const LAYER_QUESTIONS: readonly string[];
 export declare class JevError extends Error {
     readonly status: number;
     readonly next?: string | undefined;
@@ -22,3 +29,12 @@ export declare function askJev(a: {
     model?: string;
     fetch?: typeof fetch;
 }): Promise<Asked>;
+/** A free grade on the coordination layer (or one paid from a Taifoon key's balance, with `apiKey`): the layer asks Jev the
+ *  four RUBRIC questions on `text` and returns the answers; this package composes the verdict from them as with a key. */
+export declare function askLayer(a: {
+    text: string;
+    questions: readonly Question[];
+    layer?: string;
+    apiKey?: string | null;
+    fetch?: typeof fetch;
+}): Promise<Asked>;

package/dist/ask.js

@@ -1,6 +1,10 @@
 export const TYPESAFE_URL = 'https://api.typesafe.ai';
 /** The model every key-path call asks for. Pinned, not `jev-latest`: a record says which model answered, and an alias can move. */
 export const JEV_MODEL = 'jev-1.13.0';
+/** the coordination layer, where a caller without a TypeSafe key claims its free grades */
+export const LAYER_URL = 'https://coord.taifoon.dev';
+/** the questions the layer's free grade answers (RUBRIC_v1 asks exactly these); another rubric needs the caller's own key */
+export const LAYER_QUESTIONS = Object.freeze(['spec_met', 'unsupported_claim', 'ending', 'cheat_shaped']);
 export class JevError extends Error {
     status;
     next;
@@ -33,3 +37,29 @@ export async function askJev(a) {
     }
     return { answers, model: j.model ?? null, latency_ms: Date.now() - started, connection: 'key', trial: null };
 }
+/** A free grade on the coordination layer (or one paid from a Taifoon key's balance, with `apiKey`): the layer asks Jev the
+ *  four RUBRIC questions on `text` and returns the answers; this package composes the verdict from them as with a key. */
+export async function askLayer(a) {
+    const f = a.fetch ?? fetch;
+    const started = Date.now();
+    const other = a.questions.map((q) => q.id).filter((id) => !LAYER_QUESTIONS.includes(id));
+    if (other.length)
+        throw new JevError(`the layer's free grade answers ${LAYER_QUESTIONS.join(', ')}; this rubric also asks ${other.join(', ')}: pass { key } (your TypeSafe key)`, 400, 'grade({ key: process.env.TYPESAFE_KEY })');
+    const base = (a.layer ?? LAYER_URL).replace(/\/$/, '');
+    if (!/^https:\/\//.test(base) && !/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(base))
+        throw new JevError('the layer is only called over https', 400);
+    const r = await f(`${base}/v1/judge/compose`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-taifoon-client': '@taifoon/jev', ...(a.apiKey ? { 'x-api-key': a.apiKey } : {}) }, body: JSON.stringify({ state: a.text }), signal: AbortSignal.timeout(65_000) });
+    const j = (await r.json().catch(() => ({})));
+    if (r.status === 402)
+        throw new JevError('no free grade left for this caller today: pass { key } (your TypeSafe key), a Taifoon key (layerKey), or pay one grade with x402 at POST ' + `${base}/v1/judge/compose`, 402, `${base}/v1/judge/compose`);
+    if (!r.ok)
+        throw new JevError(`the layer answered ${r.status}${j.error ? `: ${String(j.error).slice(0, 200)}` : ''}`, r.status);
+    const answers = {};
+    for (const q of a.questions) {
+        const x = j.receipt?.answers?.[q.id];
+        if (x)
+            answers[q.id] = norm(q.id, x);
+    }
+    const g = j.quota?.grades;
+    return { answers, model: j.model ?? null, latency_ms: Date.now() - started, connection: 'trial', trial: g && typeof g.free === 'number' && typeof g.left === 'number' ? { calls: g.free, left: g.left } : null };
+}

package/dist/grade.d.ts

@@ -20,6 +20,11 @@ export type GradeInput = {
     caller?: string;
     /** base URL for `key` (default https://api.typesafe.ai) */
     endpoint?: string;
+    /** with no `key` and no `answers`: the coordination layer whose free grades are claimed (default https://coord.taifoon.dev);
+     *  false never calls it (then a key or answers are required) */
+    layer?: string | false;
+    /** a Taifoon key (tfr_…): a grade past the free ones is paid from its balance on the layer */
+    layerKey?: string | null;
     fetch?: typeof fetch;
     /** ms since epoch for the answer record; default now */
     at?: number;

package/dist/grade.js

@@ -1,5 +1,5 @@
 // grade(): evidence → deterministic facts → Jev's atomic questions → composed verdict → receipt.
-import { askJev, JevError } from './ask.js';
+import { askJev, askLayer, JevError } from './ask.js';
 import { answersOf, buildReceipt, DEFAULT_FACTS, inputFor, packOf, rubricOf } from './receipt.js';
 export async function grade(g) {
     const rubric = rubricOf(g.rubric);
@@ -17,9 +17,12 @@ export async function grade(g) {
             connection = 'supplied';
         }
         else {
-            if (!g.key)
+            if (!g.key && g.layer === false)
                 throw new JevError('pass { key } (your TypeSafe key, from console.typesafe.ai) or { answers } you already have', 400);
-            asked = await askJev({ text: jevState, questions: rubric.asked, key: g.key, endpoint: g.endpoint, fetch: g.fetch });
+            // _FREE_GRADES_v1_: no key of your own → the caller's free grades on the coordination layer (then x402 or a Taifoon key)
+            asked = g.key
+                ? await askJev({ text: jevState, questions: rubric.asked, key: g.key, endpoint: g.endpoint, fetch: g.fetch })
+                : await askLayer({ text: jevState, questions: rubric.asked, layer: g.layer || undefined, apiKey: g.layerKey, fetch: g.fetch });
             const missing = rubric.asked.filter((q) => !asked.answers[q.id]).map((q) => q.id);
             if (missing.length)
                 throw new JevError(`Jev returned no valid answer for: ${missing.join(', ')}`, 502);

package/dist/pipeline.js

@@ -1,7 +1,7 @@
 // pipeline(): one job through the coordination layer's steps, each step a function with a typed output.
 //   pick → evidence → facts → grade → record → evaluator → premium → verify
 // Every step works without the layer too: pass `evidence` (your own pack) and the layer is never read; `grade` then
-// runs on your own TypeSafe key (or answers you already have), `record` returns unsigned calls, `premium` is priced from a `sellerRecord` you pass (or skipped). With the layer
+// runs on your own TypeSafe key (or answers you already have, or without either on the caller's free grades on the layer), `record` returns unsigned calls, `premium` is priced from a `sellerRecord` you pass (or skipped). With the layer
 // (https://coord.taifoon.dev by default) the job comes from /v1/judge/queue, the pack from /v1/judge/evidence, the
 // seller's terms from /v1/pools/quote, and — only with a relayer key — the answers are recorded on the layer through
 // /v1/judge/answers/record. Nothing here signs a transaction.
@@ -156,12 +156,17 @@ export async function pipeline(o = {}) {
         }
         else if (o.key)
             g.key = o.key;
+        // _FREE_GRADES_v1_: no key → the caller's free grades on this layer (paid from relayerKey's balance past them); offline: none
+        else {
+            g.layer = layer ?? false;
+            g.layerKey = o.relayerKey ?? null;
+        }
         // 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))
+            if (!o.key && !o.answers && !layer && /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;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taifoon/jev",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "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",