byollm 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.2`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.3`) — under active development. Don't use this yet.**
 >
 > Install it deliberately: `npx byollm@alpha`, or `npm install byollm@alpha`.
 >
@@ -12,6 +12,12 @@
 > bare install resolves here too. This notice is the only guard — deliberately
 > not an npm deprecation, which would read as *abandoned* rather than *early*.
 > Ask for `@alpha` explicitly so your lockfile records that you meant to.
+>
+> **`alpha.3` is a breaking change.** A config naming `openai-http` with a
+> remote base URL and an offer scope wider than `self` is narrowed to `self`
+> until you acknowledge the spend and set a daily ceiling:
+> `byollm offer <backend> public --cap <cents>`. Local base URLs are
+> unaffected. `byollm backends` shows the cost class per route.
 
 # `byollm`
 
@@ -103,6 +109,7 @@ Off by default. A fresh daemon runs your work and nobody else's.
 ```bash
 byollm allow https://your-app.com alice   # asks you to confirm, in plain words
 byollm allow --list                       # everyone who can use this machine
+byollm offer openai public --cap 250      # share a paid backend, with a ceiling
 byollm disallow https://your-app.com alice
 ```
 

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   main
-} from "./chunk-DSQTDCOZ.js";
+} from "./chunk-2W2ZIXAS.js";
 
 // src/bin.ts
 process.exitCode = await main(process.argv.slice(2));

package/dist/{chunk-DSQTDCOZ.js → chunk-2W2ZIXAS.js}

@@ -93,9 +93,11 @@ function normalizeOrigin(input) {
 }
 
 // src/cli.ts
-import { mkdir as mkdir5, rm as rm2, stat, writeFile as writeFile5 } from "fs/promises";
+import { mkdir as mkdir6, readFile as readFile7, rm as rm2, stat, writeFile as writeFile6 } from "fs/promises";
 import { hostname, userInfo } from "os";
+import { dirname as dirname6 } from "path";
 import { createInterface } from "readline/promises";
+import { backendDescriptor as backendDescriptor3, resolveCost as resolveCost2 } from "@byollm/protocol";
 
 // src/budgets.ts
 import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
@@ -368,7 +370,8 @@ import {
   JobKind,
   OfferScope,
   backendDescriptor,
-  effectiveOfferScope
+  effectiveOfferScope,
+  resolveCost
 } from "@byollm/protocol";
 import { z as z3 } from "zod";
 
@@ -466,7 +469,31 @@ var BackendConfig = z3.object({
    * remote OpenAI-compatible server that needs one. The *name*, never the
    * value — a key does not belong in a config file the owner may share.
    */
-  apiKeyEnv: z3.string().optional()
+  apiKeyEnv: z3.string().optional(),
+  /**
+   * Required before a `metered` backend may be offered past `self`
+   * ({@link MUSTS.METERED_DEFAULTS_SELF}). There is deliberately no `cost`
+   * field: a provider's cost class comes from the protocol registry and is
+   * not the owner's to declare ({@link MUSTS.COST_NOT_CONFIGURABLE}).
+   */
+  spend: z3.object({
+    /** Set by `byollm offer`, which states the consequence in words. */
+    acknowledged: z3.boolean().default(false),
+    /**
+     * Ceiling on community spend, in whole cents, per day. A widened
+     * metered backend without one is refused
+     * ({@link MUSTS.METERED_REQUIRES_CEILING}) — "unlimited" is not a
+     * thing an owner can mean by accident.
+     */
+    dailyCapCents: z3.number().int().positive().optional(),
+    /**
+     * What this provider charges, for the ceiling estimate. Providers do
+     * not return a price, so the owner supplies one; the default is
+     * deliberately high so an unset rate trips the brake early rather
+     * than late.
+     */
+    centsPerMillionTokens: z3.number().positive().default(1500)
+  }).strict().optional()
 }).strict();
 var RouteConfig = z3.object({
   /** Key into {@link DaemonConfig.backends}. */
@@ -563,15 +590,16 @@ function resolveConfig(config) {
       continue;
     }
     const descriptor = backendDescriptor(backend.backend);
+    const baseUrl = backend.baseUrl ?? descriptor.defaultBaseUrl;
     if (descriptor.class === "http") {
-      if (backend.baseUrl === void 0) {
+      if (baseUrl === void 0) {
         problems.push({
           where: `backends.${route.backend}`,
           message: "an HTTP-class backend needs a baseUrl"
         });
         continue;
       }
-      const check = checkBaseUrl(backend.baseUrl);
+      const check = checkBaseUrl(baseUrl);
       if (!check.ok) {
         problems.push({
           where: `backends.${route.backend}.baseUrl`,
@@ -580,12 +608,25 @@ function resolveConfig(config) {
         continue;
       }
     }
+    const cost = resolveCost(backend.backend, baseUrl);
+    const acknowledged = backend.spend?.acknowledged === true;
+    const capCents = backend.spend?.dailyCapCents;
+    const widened = backend.offer !== "self";
+    if (cost === "metered" && widened && acknowledged && capCents === void 0) {
+      problems.push({
+        where: `backends.${route.backend}.spend`,
+        message: "sharing a metered backend needs spend.dailyCapCents \u2014 an unlimited ceiling is not something anyone means on purpose"
+      });
+      continue;
+    }
     const configured = backend.offer;
-    const offerScope = effectiveOfferScope(configured, descriptor.account);
+    const offerScope = effectiveOfferScope(configured, cost, {
+      acknowledged: acknowledged && capCents !== void 0
+    });
     if (offerScope !== configured) {
       problems.push({
         where: `backends.${route.backend}.offer`,
-        message: `"${configured}" was ignored: ${descriptor.label} runs on your own subscription, so it is locked to your work only`
+        message: cost === "subscription" ? `"${configured}" was ignored: ${descriptor.label} runs on your own subscription, so it is locked to your work only` : `"${configured}" was narrowed to "self": ${descriptor.label} bills you per token. \`byollm offer ${route.backend} ${configured}\` to share it deliberately, with a ceiling`
       });
     }
     routes.push({
@@ -594,8 +635,12 @@ function resolveConfig(config) {
       backendId: backend.backend,
       backendClass: descriptor.class,
       model: route.model,
+      cost,
       offerScope,
-      baseUrl: backend.baseUrl,
+      spendAcknowledged: acknowledged,
+      spendDailyCapCents: capCents,
+      spendCentsPerMillionTokens: backend.spend?.centsPerMillionTokens ?? 1500,
+      baseUrl,
       apiKeyEnv: backend.apiKeyEnv
     });
   }
@@ -907,6 +952,97 @@ var Pairings = class {
   }
 };
 
+// src/spend.ts
+import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname5 } from "path";
+import { z as z6 } from "zod";
+var SpendFile = z6.object({
+  version: z6.literal(1),
+  /** Per backend key: epoch-ms timestamps and the cents charged. */
+  entries: z6.record(
+    z6.string(),
+    z6.array(
+      z6.object({ at: z6.number().int().positive(), cents: z6.number().min(0) })
+    )
+  )
+}).strict();
+var SpendLedger = class {
+  #path;
+  #entries = {};
+  #loaded = false;
+  constructor(path) {
+    this.#path = path;
+  }
+  async load(now) {
+    try {
+      const parsed = SpendFile.safeParse(
+        JSON.parse(await readFile6(this.#path, "utf8"))
+      );
+      this.#entries = parsed.success ? parsed.data.entries : {};
+    } catch {
+      this.#entries = {};
+    }
+    this.#prune(now);
+    this.#loaded = true;
+  }
+  /** Cents spent on community work for this backend in the last 24 hours. */
+  spentTodayCents(backendKey, now) {
+    this.#assertLoaded();
+    const since = now - 864e5;
+    return (this.#entries[backendKey] ?? []).filter((e) => e.at >= since).reduce((sum, e) => sum + e.cents, 0);
+  }
+  /**
+   * Has this backend spent its daily ceiling?
+   *
+   * A backend with no ceiling reads as reached — not as unlimited. That is
+   * the safe direction and it matches the config rule: sharing without a
+   * ceiling is refused at load, so reaching this state means something is
+   * inconsistent and the brake should be on.
+   */
+  hasReachedCeiling(backendKey, capCents, now) {
+    if (capCents === void 0) return true;
+    return this.spentTodayCents(backendKey, now) >= capCents;
+  }
+  /** Record an estimated charge for community work. */
+  async record(backendKey, cents, now) {
+    this.#assertLoaded();
+    (this.#entries[backendKey] ??= []).push({ at: now, cents });
+    this.#prune(now);
+    await mkdir5(dirname5(this.#path), { recursive: true });
+    await writeFile5(
+      this.#path,
+      JSON.stringify({ version: 1, entries: this.#entries }),
+      { mode: 384 }
+    );
+  }
+  /** Everything spent per backend today, for `byollm status`. */
+  summary(now) {
+    this.#assertLoaded();
+    const out = {};
+    for (const key of Object.keys(this.#entries)) {
+      out[key] = this.spentTodayCents(key, now);
+    }
+    return out;
+  }
+  #assertLoaded() {
+    if (!this.#loaded) throw new Error("spend ledger used before load()");
+  }
+  /** Anything older than a day can never affect the window again. */
+  #prune(now) {
+    const cutoff = now - 864e5;
+    const pruned = {};
+    for (const [key, entries] of Object.entries(this.#entries)) {
+      const kept = entries.filter((e) => e.at >= cutoff);
+      if (kept.length > 0) pruned[key] = kept;
+    }
+    this.#entries = pruned;
+  }
+};
+function estimateCents(promptChars, outputChars, centsPerMillionTokens) {
+  const tokens = (promptChars + outputChars) / 4;
+  return tokens / 1e6 * centsPerMillionTokens;
+}
+
 // src/paths.ts
 import { homedir } from "os";
 import { join } from "path";
@@ -918,6 +1054,7 @@ function daemonPaths(root = defaultRoot()) {
     allowlist: join(root, "allow.json"),
     ingressLog: join(root, "ingress.log"),
     budgets: join(root, "budgets.json"),
+    spend: join(root, "spend.json"),
     pauseFlag: join(root, "paused"),
     scratch: join(root, "scratch")
   };
@@ -929,13 +1066,15 @@ function defaultRoot() {
 // src/runner.ts
 import {
   REFUSAL_MESSAGES,
-  backendDescriptor as backendDescriptor2,
   matchAudience,
   payloadTextLength
 } from "@byollm/protocol";
 
 // src/backends/index.ts
-import { BACKEND_IDS } from "@byollm/protocol";
+import {
+  BACKEND_IDS,
+  backendDescriptor as backendDescriptor2
+} from "@byollm/protocol";
 
 // src/backends/claude-cli.ts
 import { execFile, spawn } from "child_process";
@@ -1368,12 +1507,10 @@ function describeFetchError(error, origin) {
 
 // src/backends/index.ts
 function createBackend(id, init) {
-  switch (id) {
-    case "openai-http":
-      return new OpenAiHttpBackend(init);
-    case "claude-cli":
-      return new ClaudeCliBackend();
+  if (backendDescriptor2(id).class === "process") {
+    return new ClaudeCliBackend();
   }
+  return new OpenAiHttpBackend(init);
 }
 var IMPLEMENTED_BACKEND_IDS = BACKEND_IDS;
 
@@ -1485,6 +1622,21 @@ var Runner = class {
     }
     return backend;
   }
+  /**
+   * Has this route spent the owner's daily ceiling on other people's work?
+   *
+   * Only meaningful for `metered` routes; `free` and `subscription` never
+   * reach here in a way that matters, because the matcher refuses them for
+   * other reasons first ({@link MUSTS.METERED_REQUIRES_CEILING}).
+   */
+  #spendCeilingReached(route) {
+    if (route.cost !== "metered") return false;
+    return this.#options.spend.hasReachedCeiling(
+      route.backendKey,
+      route.spendDailyCapCents,
+      this.#now()
+    );
+  }
   #routeFor(kind) {
     return this.#options.loaded.routes.find((route) => route.kind === kind);
   }
@@ -1512,7 +1664,11 @@ var Runner = class {
       {
         owner: this.#options.owner,
         offerScope: route.offerScope,
-        account: backendDescriptor2(route.backendId).account,
+        cost: route.cost,
+        spend: {
+          acknowledged: route.spendAcknowledged,
+          ceilingReached: this.#spendCeilingReached(route)
+        },
         // The daemon's own list — the whole point of Rev 1 §B.
         locallyAllows: this.#options.allowlist.predicateFor(
           this.#options.client.origin
@@ -1599,6 +1755,17 @@ var Runner = class {
         outputChars: result.ok ? result.text.length : 0,
         ...result.ok ? {} : { detail: result.message }
       });
+      if (community && route.cost === "metered") {
+        await this.#options.spend.record(
+          route.backendKey,
+          estimateCents(
+            prompt.length,
+            result.ok ? result.text.length : 0,
+            route.spendCentsPerMillionTokens
+          ),
+          this.#now()
+        );
+      }
       this.#completed += 1;
       this.#options.onEvent?.({
         type: "finished",
@@ -1791,6 +1958,7 @@ var USAGE = `byollm \u2014 run an app's LLM jobs on your own models.
   byollm resume               start claiming again
   byollm allow <url> <user>   let someone else's jobs run here (named audience)
   byollm allow --list         who can currently use this machine
+  byollm offer <backend> <scope>  who a backend is offered to (self|named|public)
   byollm disallow <url> <user>
   byollm forget <url>         drop a pairing
   byollm backends             what is installed, healthy, and advertised
@@ -1836,6 +2004,8 @@ async function runCli(argv, options = {}) {
       return commandAllow(paths, rest, io);
     case "disallow":
       return commandDisallow(paths, rest, io);
+    case "offer":
+      return commandOffer(paths, rest, io);
     case "forget":
       return commandForget(paths, rest, io);
     case "backends":
@@ -1854,7 +2024,7 @@ async function commandConnect(paths, args, io, signal) {
     return 2;
   }
   const origin = normalizeOrigin(target);
-  const { loaded, ingress, allowlist, budgets } = await context(paths);
+  const { loaded, ingress, allowlist, budgets, spend } = await context(paths);
   for (const problem of loaded.problems) {
     io.err(`config: ${problem.where}: ${problem.message}
 `);
@@ -1868,6 +2038,7 @@ async function commandConnect(paths, args, io, signal) {
     loaded,
     allowlist,
     budgets,
+    spend,
     ingress
   });
   const capabilities = await runner.detectCapabilities();
@@ -1934,7 +2105,7 @@ async function commandRun(paths, args, io, signal) {
   return runLoop(paths, origins, io, signal);
 }
 async function runLoop(paths, origins, io, signal) {
-  const { loaded, ingress, allowlist, budgets } = await context(paths);
+  const { loaded, ingress, allowlist, budgets, spend } = await context(paths);
   const pairings = new Pairings(paths.pairings);
   await pairings.load();
   const controller = new AbortController();
@@ -1961,6 +2132,7 @@ async function runLoop(paths, origins, io, signal) {
       loaded,
       allowlist,
       budgets,
+      spend,
       ingress,
       onEvent: (event) => {
         report(origin, event, io);
@@ -2017,7 +2189,7 @@ function report(origin, event, io) {
   }
 }
 async function commandStatus(paths, io) {
-  const { loaded, ingress, allowlist, budgets } = await context(paths);
+  const { loaded, ingress, allowlist, budgets, spend } = await context(paths);
   const pairings = new Pairings(paths.pairings);
   await pairings.load();
   const paused = await isPaused(paths);
@@ -2063,6 +2235,19 @@ async function commandStatus(paths, io) {
 `
     );
   }
+  const spentToday = spend.summary(now);
+  const metered = loaded.routes.filter((r) => r.cost === "metered");
+  if (metered.length > 0) {
+    io.out("\nmetered backends \u2014 your money\n");
+    for (const route of metered) {
+      const spent = spentToday[route.backendKey] ?? 0;
+      io.out(
+        route.spendAcknowledged ? `  ${route.backendKey}: ${spent.toFixed(1)}c spent today of ${String(route.spendDailyCapCents ?? 0)}c
+` : `  ${route.backendKey}: not shared \u2014 your work only
+`
+      );
+    }
+  }
   const usage = budgets.usage(now);
   io.out("\ncommunity work done for others\n");
   io.out(
@@ -2134,9 +2319,9 @@ function indent(text) {
   return text.split("\n").map((line) => `           ${line}`).join("\n");
 }
 async function commandPause(paths, pause, io) {
-  await mkdir5(paths.root, { recursive: true });
+  await mkdir6(paths.root, { recursive: true });
   if (pause) {
-    await writeFile5(paths.pauseFlag, `${(/* @__PURE__ */ new Date()).toISOString()}
+    await writeFile6(paths.pauseFlag, `${(/* @__PURE__ */ new Date()).toISOString()}
 `);
     io.out(
       "paused \u2014 no new work will be claimed. `byollm resume` to start again.\n"
@@ -2204,6 +2389,129 @@ Allow ${owner} to use this machine?`
 `);
   return 0;
 }
+async function commandOffer(paths, args, io) {
+  const [backendKey, scope, ...rest] = args;
+  if (backendKey === void 0 || scope === void 0) {
+    io.err(
+      "usage: byollm offer <backend> <self|named|public> [--cap <cents>]\n"
+    );
+    return 2;
+  }
+  if (scope !== "self" && scope !== "named" && scope !== "public") {
+    io.err(`"${scope}" is not an offer scope \u2014 use self, named, or public
+`);
+    return 2;
+  }
+  const capIndex = rest.indexOf("--cap");
+  let capCents;
+  if (capIndex !== -1) {
+    const raw2 = rest[capIndex + 1];
+    const parsed2 = Number(raw2);
+    if (raw2 === void 0 || !Number.isFinite(parsed2) || parsed2 <= 0) {
+      io.err("--cap takes a number of cents per day, greater than zero\n");
+      return 2;
+    }
+    capCents = Math.round(parsed2);
+  }
+  let raw;
+  try {
+    raw = await readFile7(paths.config, "utf8");
+  } catch {
+    io.err(
+      `no config at ${paths.config} \u2014 nothing to offer yet.
+Write one, or run \`byollm connect <url>\` first.
+`
+    );
+    return 1;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    io.err(`${paths.config} is not valid JSON \u2014 fix it by hand first
+`);
+    return 1;
+  }
+  const result = DaemonConfig.safeParse(parsed);
+  if (!result.success) {
+    io.err(`${paths.config} is not a valid byollm config \u2014 fix it first
+`);
+    return 1;
+  }
+  const backend = result.data.backends[backendKey];
+  if (!backend) {
+    const known = Object.keys(result.data.backends);
+    io.err(
+      `no backend named "${backendKey}" in ${paths.config}
+` + (known.length > 0 ? `configured: ${known.join(", ")}
+` : "")
+    );
+    return 2;
+  }
+  const descriptor = backendDescriptor3(backend.backend);
+  const baseUrl = backend.baseUrl ?? descriptor.defaultBaseUrl;
+  const cost = resolveCost2(backend.backend, baseUrl);
+  const widening = scope !== "self";
+  if (cost === "subscription" && widening) {
+    io.err(
+      `${descriptor.label} runs on your own subscription, whose terms cover
+your work and nobody else's. It cannot be offered to other people.
+`
+    );
+    return 1;
+  }
+  if (cost === "metered" && widening) {
+    const cap = capCents ?? backend.spend?.dailyCapCents;
+    if (cap === void 0) {
+      io.err(
+        `${descriptor.label} bills you per token, so sharing it needs a daily
+ceiling. Add one: \`byollm offer ${backendKey} ${scope} --cap <cents>\`
+`
+      );
+      return 2;
+    }
+    const dollars = (cap / 100).toFixed(2);
+    const confirmed = await io.confirm(
+      `
+This lets other people's jobs run on ${descriptor.label}, which bills
+your account per token. You would be paying for their work, up to
+$${dollars} a day, every day, until you change it.
+Spending stops at that ceiling and resumes the next day.
+
+Offer ${backendKey} to ${scope === "public" ? "anyone" : "people you have allowed"}?`
+    );
+    if (!confirmed) {
+      io.out("nothing changed\n");
+      return 0;
+    }
+    result.data.backends[backendKey] = {
+      ...backend,
+      offer: scope,
+      spend: {
+        centsPerMillionTokens: backend.spend?.centsPerMillionTokens ?? 1500,
+        ...backend.spend,
+        acknowledged: true,
+        dailyCapCents: cap
+      }
+    };
+  } else {
+    result.data.backends[backendKey] = {
+      ...backend,
+      offer: scope,
+      // Narrowing back to `self` withdraws the consent too, so a later
+      // widening has to be agreed to again rather than inherited.
+      ...cost === "metered" && !widening && backend.spend !== void 0 ? { spend: { ...backend.spend, acknowledged: false } } : {}
+    };
+  }
+  await mkdir6(dirname6(paths.config), { recursive: true });
+  await writeFile6(paths.config, `${JSON.stringify(result.data, null, 2)}
+`);
+  const written = result.data.backends[backendKey].spend?.dailyCapCents;
+  io.out(
+    `${backendKey} is now offered to ${scope}` + (written === void 0 || !widening ? "" : `, capped at ${String(written)}c a day`) + "\n"
+  );
+  return 0;
+}
 async function commandDisallow(paths, args, io) {
   const [rawOrigin, owner] = args;
   if (rawOrigin === void 0 || owner === void 0) {
@@ -2237,7 +2545,7 @@ async function commandForget(paths, args, io) {
   return 0;
 }
 async function commandBackends(paths, io) {
-  const { loaded, ingress, allowlist, budgets } = await context(paths);
+  const { loaded, ingress, allowlist, budgets, spend } = await context(paths);
   const runner = new Runner({
     client: new ProtocolClient({ origin: "https://unused.invalid" }),
     runnerId: "local",
@@ -2246,6 +2554,7 @@ async function commandBackends(paths, io) {
     loaded,
     allowlist,
     budgets,
+    spend,
     ingress
   });
   const advertised = await runner.detectCapabilities();
@@ -2253,8 +2562,10 @@ async function commandBackends(paths, io) {
   io.out("configured routes\n");
   for (const route of loaded.routes) {
     const ok = advertisedKinds.has(route.kind);
+    const pays = route.cost === "free" ? "free (your electricity)" : route.cost === "subscription" ? "your subscription \u2014 locked to your work" : route.spendAcknowledged ? `metered \u2014 shared, cap ${String(route.spendDailyCapCents ?? 0)}c/day` : "metered \u2014 your money, not shared";
     io.out(
       `  ${ok ? "\u2713" : "\u2717"} ${route.kind.padEnd(14)} ${route.backendId}:${route.model}${route.baseUrl === void 0 ? "" : ` @ ${route.baseUrl}`}
+      ${pays}
 `
     );
   }
@@ -2282,7 +2593,9 @@ async function context(paths) {
   await allowlist.load();
   const budgets = new Budgets(paths.budgets, loaded.config.community);
   await budgets.load(Date.now());
-  return { loaded, ingress, allowlist, budgets };
+  const spend = new SpendLedger(paths.spend);
+  await spend.load(Date.now());
+  return { loaded, ingress, allowlist, budgets, spend };
 }
 async function confirmInteractively(question) {
   if (!process.stdin.isTTY) {
@@ -2321,7 +2634,7 @@ async function main(argv) {
 }
 
 // src/index.ts
-var DAEMON_VERSION = "0.1.0-alpha.2";
+var DAEMON_VERSION = "0.1.0-alpha.3";
 
 export {
   Allowlist,
@@ -2341,6 +2654,8 @@ export {
   hashText,
   stripControlChars,
   Pairings,
+  SpendLedger,
+  estimateCents,
   daemonPaths,
   defaultRoot,
   childEnv,
@@ -2355,4 +2670,4 @@ export {
   runCli,
   main
 };
-//# sourceMappingURL=chunk-DSQTDCOZ.js.map
+//# sourceMappingURL=chunk-2W2ZIXAS.js.map