jevable 0.1.1 → 0.1.2

package/README.md

@@ -4,7 +4,9 @@ Make your monitor smart. An agent watching a log, a feed or an API is woken
 by every line, or by a grep that misses what nobody foresaw. `jevable` sits in
 between: plain conditions do what grep does, and a question answered by
 [Jev](https://docs.typesafe.ai), TypeSafe's fast and cheap classification
-model, decides the rest. Only what matters wakes the agent, or reaches you.
+model, decides the rest. Only what matters wakes the agent, or reaches you —
+and every wake it holds back is an agent turn you do not pay for, while a Jev
+question costs about $0.00002.
 
 ## One prompt, any agent
 
@@ -26,13 +28,14 @@ The agent writes the rule, tests it on real events and on the edge cases you
 named, and arms it the way its runtime can be woken: a background command
 that ends at the next match and wakes the agent (restarted after each one), a
 stream of notifications (Claude Code's Monitor), or a watch that runs on after
-the session and pushes to your phone or resumes the session. It asks you once
-for a TypeSafe API key and keeps it in `~/.jevable/key`.
+the session and pushes to your phone or resumes the session. For Jev it needs
+one API key from TypeSafe, OpenRouter or Vercel AI Gateway: it finds the one
+you have, or asks you to paste one and sets it up.
 
 ## By hand
 
 ```bash
-export TYPESAFE_API_KEY=...          # or put it in ~/.jevable/key
+npx -y jevable key sk-or-v1-...      # an API key from TypeSafe, OpenRouter or Vercel AI Gateway
 npx -y jevable filter --json --from 'tail -n 0 -F app.log' \
   'line.contains("ERROR") && judge.boolean(line, "Does this log line report that a service or a dependency it needs is down or unreachable?") >= 0.7'
 ```
@@ -41,6 +44,7 @@ Node 20+. `npx -y jevable <command>` needs no install; `npm i -g jevable` gives
 
 - `jevable filter [RULE]` — print what passes, from stdin or `--from CMD`. `--json`, `--key`, `--cooldown`, `--window`, `-m`, `--state`, `--all`.
 - `jevable test [RULE] --yes ... --no ...` — run a rule on samples, show the scores and the thresholds that separate them.
+- `jevable key [KEY]` — whether there is a working key for Jev; given an API key from TypeSafe, OpenRouter or Vercel AI Gateway, check it and save it.
 - `jevable guide` — everything an agent needs: the steps, how each runtime gets the events back, rules, options, recipes ([guide.md](guide.md)).
 
 ## As a library

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // The jevable command line: filter, test, guide.
 import { filterCommand } from "./commands/filter.js";
+import { keyCommand } from "./commands/key.js";
 import { testCommand } from "./commands/test.js";
 import { log, packageFile } from "./common.js";
 const HELP = `jevable — make your monitor smart
@@ -15,11 +16,11 @@ a fast and cheap classification model, a semantic question.
 Commands:
   filter [RULE]                  print the records (or windows) that pass RULE
   test [RULE] --yes .. --no ..   run RULE on samples and show the scores
+  key [KEY]                      whether there is a working key for Jev; with KEY, check and save it
   guide                          what to do and how: steps for agents, rules, options, recipes
 
 Agents: read \`jevable guide\` first and follow it.
-Setup: export TYPESAFE_API_KEY (or JEV_API_KEY), or put the key in ~/.jevable/key.
-       JEV_BASE_URL for a proxy, JEV_MODEL to pin a model.
+Setup: \`jevable key\`. Any API key from TypeSafe, OpenRouter or Vercel AI Gateway works.
 Run \`jevable <command> --help\` for a command's options.
 `;
 async function main([cmd, ...args]) {
@@ -28,6 +29,8 @@ async function main([cmd, ...args]) {
             return filterCommand(args);
         case "test":
             return testCommand(args);
+        case "key":
+            return keyCommand(args);
         case "guide":
             process.stdout.write(packageFile("guide.md"));
             return 0;

package/dist/commands/key.d.ts

@@ -0,0 +1,2 @@
+export declare const KEY_HELP = "jevable key [KEY]\n\nWithout KEY: whether jevable has a key for Jev, and whether it works.\nWith KEY: tell whose key it is (TypeSafe, OpenRouter or Vercel AI Gateway),\ncheck it with one question, and save it in ~/.jevable/env, where every\nruntime and detached watch finds it.\n\nExit status: 0 when a working key is in place, 1 when not.\n";
+export declare function keyCommand(args: string[]): Promise<number>;

package/dist/commands/key.js

@@ -0,0 +1,77 @@
+// `jevable key`: is there a key for Jev, and does it work? Given a key: whose
+// it is, checked with one question and saved where every runtime and detached
+// watch finds it. The person pastes a key; they never pick a provider or a
+// variable name.
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+import { Client, lookup, whose } from "@jevable/core";
+import { ENV_FILE, provider, settings } from "../common.js";
+export const KEY_HELP = `jevable key [KEY]
+
+Without KEY: whether jevable has a key for Jev, and whether it works.
+With KEY: tell whose key it is (TypeSafe, OpenRouter or Vercel AI Gateway),
+check it with one question, and save it in ~/.jevable/env, where every
+runtime and detached watch finds it.
+
+Exit status: 0 when a working key is in place, 1 when not.
+`;
+const ASK = "Ask the person for an API key from TypeSafe, OpenRouter or Vercel AI Gateway, then run: jevable key <the key>";
+export async function keyCommand(args) {
+    const { values: v, positionals } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean", short: "h" } } });
+    if (v.help)
+        return say(KEY_HELP.trimEnd(), 0);
+    const { vars, fromFile } = settings();
+    if (positionals[0])
+        return save(positionals[0].trim(), vars);
+    const found = provider(vars);
+    if (!found?.key)
+        return say(`No key for Jev. ${ASK}`, 1);
+    const where = fromFile.has(found.variable) ? "in ~/.jevable/env" : `from ${found.variable}`;
+    const r = await check(found.provider, found.key);
+    if ("error" in r)
+        return say(`The ${found.provider.label} key ${where} does not work: ${r.error}. ${ASK}`, 1);
+    return say(`Jev via ${found.provider.label}, key ${where}; it works (${r.seconds} s).`, 0);
+}
+async function save(key, vars) {
+    // A custom endpoint (JEV_BASE_URL) takes any key; otherwise the key says whose it is.
+    const p = vars.JEV_BASE_URL ? lookup(vars)[0].provider : whose(key);
+    if (!p)
+        return say("That is not a key for Jev: TypeSafe keys start with apikey_, OpenRouter keys with sk-or-, Vercel AI Gateway keys with vck_.", 1);
+    const r = await check(p, key);
+    if ("error" in r)
+        return say(`The ${p.label} key does not work: ${r.error}. Nothing saved.`, 1);
+    // Name the provider too, so a key saved now wins over an older one elsewhere.
+    writeEnv(p.name === "custom" ? { [p.env[0]]: key } : { [p.env[0]]: key, JEV_PROVIDER: p.name });
+    return say(`Saved the ${p.label} key in ~/.jevable/env; it works (${r.seconds} s).`, 0);
+}
+/** One question, to see the key and the endpoint work. */
+async function check(p, key) {
+    const client = new Client({ apiKey: key, baseUrl: p.baseUrl, model: p.model, provider: p.label });
+    const start = performance.now();
+    try {
+        await client.ask("jevable key", { q: { type: "noul", instructions: "Is this text a command?" } });
+        return { seconds: ((performance.now() - start) / 1000).toFixed(2) };
+    }
+    catch (err) {
+        return { error: err.message.replace(/\.$/, "") };
+    }
+}
+/** Sets NAME=value lines in ~/.jevable/env, keeping the rest; readable by the owner only. */
+function writeEnv(set) {
+    let lines = [];
+    try {
+        lines = readFileSync(ENV_FILE, "utf8").split("\n").filter(Boolean);
+    }
+    catch { }
+    lines = lines.filter((l) => !Object.keys(set).includes(l.match(/^\s*(?:export\s+)?([A-Za-z_]\w*)\s*=/)?.[1] ?? ""));
+    for (const [name, value] of Object.entries(set))
+        lines.push(`${name}=${value}`);
+    mkdirSync(dirname(ENV_FILE), { recursive: true, mode: 0o700 });
+    writeFileSync(ENV_FILE, `${lines.join("\n")}\n`, { mode: 0o600 });
+    chmodSync(ENV_FILE, 0o600);
+}
+function say(text, code) {
+    process.stdout.write(`${text}\n`);
+    return code;
+}

package/dist/commands/providers.d.ts

@@ -0,0 +1,2 @@
+export declare const PROVIDERS_HELP = "jevable providers [--check]\n\nWhere jevable can reach Jev (TypeSafe's classification model), the key it\nfound for each \u2014 in the environment or in ~/.jevable/env \u2014 and the one it\nuses: JEV_PROVIDER if set, else the first with a key.\n\nOptions:\n  --check   ask each provider with a key one question, to see that the key works\n            (a fraction of a cent each)\n\nExit status: 0 when a provider has a key (and, with --check, answered), 1 when none does.\n";
+export declare function providersCommand(args: string[]): Promise<number>;

package/dist/commands/providers.js

@@ -0,0 +1,54 @@
+// `jevable providers`: where jevable can reach Jev, which key it found for
+// each, and which one it uses — so an agent knows before asking anyone.
+import { parseArgs } from "node:util";
+import { Client, lookup } from "@jevable/core";
+import { provider, settings } from "../common.js";
+export const PROVIDERS_HELP = `jevable providers [--check]
+
+Where jevable can reach Jev (TypeSafe's classification model), the key it
+found for each — in the environment or in ~/.jevable/env — and the one it
+uses: JEV_PROVIDER if set, else the first with a key.
+
+Options:
+  --check   ask each provider with a key one question, to see that the key works
+            (a fraction of a cent each)
+
+Exit status: 0 when a provider has a key (and, with --check, answered), 1 when none does.
+`;
+export async function providersCommand(args) {
+    const { values: v } = parseArgs({ args, options: { check: { type: "boolean" }, help: { type: "boolean", short: "h" } } });
+    if (v.help) {
+        process.stdout.write(PROVIDERS_HELP);
+        return 0;
+    }
+    const { vars, fromFile } = settings();
+    const found = lookup(vars);
+    const used = provider(vars);
+    const where = (f) => (f.variable ? `${f.variable} (${fromFile.has(f.variable) ? "~/.jevable/env" : "environment"})` : `no ${f.provider.env[0]}`);
+    const rows = await Promise.all(found.map(async (f) => [f.provider.name, where(f), f.provider.name === used?.provider.name ? "← used" : "", v.check && f.key ? await check(f) : ""]));
+    const width = rows[0].map((_, i) => Math.max(...rows.map((r) => r[i].length)));
+    for (const r of rows)
+        process.stdout.write(`${r.map((c, i) => c.padEnd(width[i])).join("  ").trimEnd()}\n`);
+    if (!used?.key) {
+        process.stdout.write(`\nNo key for Jev. Put one of these in ~/.jevable/env (one NAME=value per line):\n`);
+        const named = found.filter((f) => f.provider.keys);
+        const pad = Math.max(...named.map((f) => f.provider.env[0].length)) + 4;
+        for (const f of named)
+            process.stdout.write(`  ${`${f.provider.env[0]}=...`.padEnd(pad)}  ${f.provider.label}, keys at ${f.provider.keys}\n`);
+        return 1;
+    }
+    return v.check && !rows.find((r) => r[2])?.[3].startsWith("ok") ? 1 : 0;
+}
+/** One question, to see the key and the endpoint work. */
+async function check(f) {
+    const p = f.provider;
+    const client = new Client({ apiKey: f.key, baseUrl: p.baseUrl, model: p.model, provider: p.label });
+    const start = performance.now();
+    try {
+        await client.ask("jevable providers --check", { q: { type: "noul", instructions: "Is this text a command?" } });
+        return `ok ${((performance.now() - start) / 1000).toFixed(2)} s`;
+    }
+    catch (err) {
+        return `failed: ${err.message.slice(0, 120)}`;
+    }
+}

package/dist/common.d.ts

@@ -1,7 +1,19 @@
-import { Engine } from "@jevable/core";
+import { Engine, type Found } from "@jevable/core";
 import type { FilterResult } from "./run/filter.ts";
 export declare function packageFile(name: string): string;
 export declare const log: (msg: string) => void;
+export declare const ENV_FILE: string;
+/**
+ * The environment, with ~/.jevable/env (NAME=value lines) filling in what it
+ * lacks: for runtimes that keep secrets out of a command's environment (dsh
+ * drops every variable named *KEY*) and for watches started elsewhere.
+ */
+export declare function settings(): {
+    vars: Record<string, string | undefined>;
+    fromFile: Set<string>;
+};
+/** The provider of Jev to use, from the environment: JEV_PROVIDER, else the first with a key. */
+export declare function provider(vars?: Record<string, string | undefined>): Found | undefined;
 /** The shared engine, configured from the environment. A missing key is reported by the first judge call. */
 export declare function newEngine(model?: string): Engine;
 /** The rule from the positional argument or -f, exactly one. */

package/dist/common.js

@@ -3,7 +3,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { Client, Engine } from "@jevable/core";
+import { choose, Client, Engine, lookup } from "@jevable/core";
 // guide.md and package.json sit at the package root, next to src/ and dist/.
 const PACKAGE_ROOT = new URL("../", import.meta.url);
 export function packageFile(name) {
@@ -12,21 +12,39 @@ export function packageFile(name) {
 export const log = (msg) => {
     process.stderr.write(`jevable: ${msg}\n`);
 };
-/** The shared engine, configured from the environment. A missing key is reported by the first judge call. */
-export function newEngine(model) {
-    const env = process.env;
-    const apiKey = env.JEV_API_KEY || env.TYPESAFE_API_KEY || keyFile();
-    return new Engine(new Client({ apiKey, baseUrl: env.JEV_BASE_URL, model: model || env.JEV_MODEL }));
-}
-// ~/.jevable/key: for runtimes that keep secrets out of a command's environment
-// (dsh drops every variable named *KEY*) and for watches started elsewhere.
-function keyFile() {
+export const ENV_FILE = join(homedir(), ".jevable", "env");
+/**
+ * The environment, with ~/.jevable/env (NAME=value lines) filling in what it
+ * lacks: for runtimes that keep secrets out of a command's environment (dsh
+ * drops every variable named *KEY*) and for watches started elsewhere.
+ */
+export function settings() {
+    const vars = { ...process.env };
+    const fromFile = new Set();
+    let text = "";
     try {
-        return readFileSync(join(homedir(), ".jevable", "key"), "utf8").trim() || undefined;
+        text = readFileSync(ENV_FILE, "utf8");
     }
-    catch {
-        return undefined;
+    catch { }
+    for (const line of text.split("\n")) {
+        const m = line.match(/^\s*(?:export\s+)?([A-Za-z_]\w*)\s*=\s*(.*?)\s*$/);
+        if (!m || vars[m[1]])
+            continue;
+        vars[m[1]] = m[2].replace(/^(["'])(.*)\1$/, "$2");
+        fromFile.add(m[1]);
     }
+    return { vars, fromFile };
+}
+/** The provider of Jev to use, from the environment: JEV_PROVIDER, else the first with a key. */
+export function provider(vars = settings().vars) {
+    return choose(lookup(vars), vars.JEV_PROVIDER);
+}
+/** The shared engine, configured from the environment. A missing key is reported by the first judge call. */
+export function newEngine(model) {
+    const { vars } = settings();
+    const found = provider(vars);
+    const p = found?.provider;
+    return new Engine(new Client({ apiKey: found?.key, baseUrl: p?.baseUrl, model: model || vars.JEV_MODEL || p?.model, provider: p?.label }));
 }
 /** The rule from the positional argument or -f, exactly one. */
 export function ruleSource(positionals, file) {
@@ -44,5 +62,6 @@ export function printStats(r, noun, engine) {
     const { calls, cacheHits, tokens } = engine.stats;
     const unit = r.count === 1 ? noun.replace(/s$/, "") : noun;
     const held = r.emitted >= 0 && r.emitted !== r.passed ? ` (${r.emitted} emitted, the rest held back by --key/--cooldown)` : "";
-    log(`${r.count} ${unit} · ${r.passed} passed${held} · ${calls} Jev calls (+${cacheHits} from cache) · ${tokens} tokens`);
+    const via = calls ? ` via ${engine.client.provider}` : "";
+    log(`${r.count} ${unit} · ${r.passed} passed${held} · ${calls} Jev calls${via} (+${cacheHits} from cache) · ${tokens} tokens`);
 }

package/guide.md

@@ -4,7 +4,8 @@ A watch that wakes you on every line buries you in noise; a grep strict enough
 to stay quiet misses what nobody foresaw. jevable sits between the events and
 whatever wakes you: plain conditions do what grep does, and a question that
 Jev (TypeSafe's classification model) answers in about 0.3 s for a tiny
-fraction of a cent decides the rest. Only what matters comes out.
+fraction of a cent decides the rest. Only what matters comes out, so you
+miss less and spend a turn only when something counts.
 
     jevable filter --json --from 'tail -n 0 -F app.log' \
       'line.contains("ERROR") && judge.boolean(line, "Does this log line report that a service or a dependency it needs is down or unreachable?") >= 0.7'
@@ -22,12 +23,12 @@ incident", "when a reviewer asks for a change on PR 12, make it". Do this:
 1. **Pin it down**: where the events come from, what counts, what happens
    then (you act, or the person is told), and for how long (one event, while
    this session is open, or days). Ask only what you cannot work out.
-2. **Key.** jevable reads `TYPESAFE_API_KEY` (or `JEV_API_KEY`), else the file
-   `~/.jevable/key`. If there is none, ask the person for a TypeSafe API key
-   (docs.typesafe.ai) and save it:
-   `mkdir -p ~/.jevable && printf '%s\n' "$KEY" > ~/.jevable/key && chmod 600 ~/.jevable/key`.
-   The file also reaches runtimes that strip keys from a command's environment
-   (dsh) and watches started outside your shell. Never put the key in a repository.
+2. **Key.** Run `jevable key`. If it has no working key, ask the person:
+   "Do you have an API key from TypeSafe, OpenRouter or Vercel AI Gateway?
+   Paste it here." Then run `jevable key <the key>`: it tells whose key it is,
+   checks it and saves it where every runtime and detached watch finds it. Do
+   not make the person choose a provider or set a variable, and never put a
+   key in a repository.
 3. **Source**: a command that prints one event per line — `tail -n 0 -F` a
    log, an API polled in a loop, a feed (Recipes). Keep everything for this
    watch in `~/.jevable/<name>/`; a longer source goes in `source.sh` there. Run it
@@ -149,7 +150,7 @@ Flags change between versions: check them with your runtime's `--help`.
   out; an extension that watches processes can wake you instead. After the session:
   `pi -p --session "$PI_SESSION_FILE" "..." </dev/null`, only while no pi
   window has the session open.
-- **dsh.** It strips `*KEY*` variables: use `~/.jevable/key`. A finished
+- **dsh.** It strips `*KEY*` variables: save the key with `jevable key`, which keeps it in a file. A finished
   background task does not wake an idle session: start the `-m 1` command with
   `run_in_background: true`, then call `task_output` with `wait: true` and
   `timeout_ms: 600000` until it ends (blocking). To be woken: only under `dsh web`, by posting a `session.prompt`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jevable",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "grep that reads meaning: pass through only the records a Jev judgement lets through",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@jevable/core": "0.1.1"
+    "@jevable/core": "0.1.2"
   },
   "license": "UNLICENSED"
 }