@bytesbrains/cruise 0.0.0-stage → 0.12.1

package/dist/fallback-P5KK55M4.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// Built by packages/cli/build.ts.
+import {
+  MAX_CHAIN
+} from "./chunk-FGLMW5IY.mjs";
+import "./chunk-4447IUTF.mjs";
+import "./chunk-XOH3XKM3.mjs";
+import "./chunk-42ERHAJD.mjs";
+import "./chunk-BNP63KB2.mjs";
+import "./chunk-ICJVJSTC.mjs";
+import "./chunk-UNXM6FSM.mjs";
+import "./chunk-SYTYOTO4.mjs";
+import "./chunk-O7TNRKSA.mjs";
+import "./chunk-T3ICD43U.mjs";
+import "./chunk-RT4R2W6H.mjs";
+import "./chunk-THEXUHQC.mjs";
+import {
+  lookupModel
+} from "./chunk-LALZUKEC.mjs";
+import "./chunk-5TVD3ZAI.mjs";
+import {
+  connect,
+  environmentOf,
+  parseArgs,
+  requireString,
+  run
+} from "./chunk-7NQHBXVZ.mjs";
+import "./chunk-JZPUTXM7.mjs";
+
+// src/fallbacks-write.ts
+async function setFallbacks(db, modelId, fallbacks, actor) {
+  const primary = await lookupModel(db, modelId);
+  if (primary === null || !primary.enabled) {
+    return {
+      ok: false,
+      refusal: { code: "model_not_found", message: `The model '${modelId}' does not exist or is not enabled.` }
+    };
+  }
+  const invalid = await validate(db, primary, fallbacks);
+  if (invalid !== null) return { ok: false, refusal: { code: "invalid_chain", message: invalid } };
+  const statements = [
+    db.prepare(`DELETE FROM model_fallbacks WHERE model = ?`).bind(modelId),
+    ...fallbacks.map(
+      (fallback, index) => db.prepare(`INSERT INTO model_fallbacks (model, position, fallback_model) VALUES (?, ?, ?)`).bind(modelId, index + 1, fallback)
+    ),
+    db.prepare(
+      `INSERT INTO audit_events (id, actor, action, subject, detail) VALUES (?, ?, 'model.fallbacks', ?, ?)`
+    ).bind(crypto.randomUUID(), actor, modelId, JSON.stringify({ fallbacks }))
+  ];
+  await db.batch(statements);
+  return { ok: true, model: modelId, fallbacks: [...fallbacks], warnings: await warn(db, primary, fallbacks) };
+}
+async function validate(db, primary, fallbacks) {
+  if (fallbacks.length + 1 > MAX_CHAIN) {
+    return `A chain holds at most ${MAX_CHAIN} models including the primary, so at most ${MAX_CHAIN - 1} fallback(s); ${fallbacks.length} were sent. Candidates are tried in turn against the full upstream deadline, so a long chain is a long wait rather than more redundancy.`;
+  }
+  if (new Set(fallbacks).size !== fallbacks.length) {
+    return `A model appears twice in the chain. Trying it again after it has already failed spends a deadline to learn nothing.`;
+  }
+  if (fallbacks.includes(primary.id)) {
+    return `'${primary.id}' cannot fall back to itself.`;
+  }
+  for (const id of fallbacks) {
+    const candidate = await lookupModel(db, id);
+    if (candidate === null || !candidate.enabled) {
+      return `The fallback '${id}' does not exist or is not enabled.`;
+    }
+    if (candidate.modality !== primary.modality) {
+      return `'${id}' is a ${candidate.modality} model and '${primary.id}' is a ${primary.modality} model. A chain crosses models, never modalities: the request path would reject it on every request and the chain would be redundancy in name only.`;
+    }
+  }
+  return null;
+}
+async function warn(db, primary, fallbacks) {
+  const warnings = [];
+  if (fallbacks.length === 0) {
+    warnings.push(
+      `'${primary.id}' now has no fallback. A provider's 429, 5xx or expired credential on it will reach the caller.`
+    );
+    return warnings;
+  }
+  const sameUpstream = [];
+  for (const id of fallbacks) {
+    const candidate = await lookupModel(db, id);
+    if (candidate !== null && candidate.upstreamId === primary.upstreamId) sameUpstream.push(id);
+  }
+  if (sameUpstream.length === fallbacks.length) {
+    warnings.push(
+      `Every fallback is on '${primary.upstreamId}', the primary's own upstream. Where that host rate-limits per organisation rather than per model, the chain answers the same 429 a deadline later.`
+    );
+  }
+  return warnings;
+}
+
+// scripts/fallback.ts
+run(async () => {
+  const [command, ...rest] = process.argv.slice(2);
+  const args = parseArgs(rest);
+  const db = connect(environmentOf(args));
+  switch (command) {
+    case "set": {
+      const model = requireString(args, "model");
+      const actor = requireString(args, "actor");
+      const to = requireString(args, "to");
+      const fallbacks = to.split(",").map((id) => id.trim()).filter((id) => id !== "");
+      const result = await setFallbacks(db, model, fallbacks, actor);
+      if (!result.ok) throw new Error(result.refusal.message);
+      console.log(
+        result.fallbacks.length === 0 ? `${model}: chain cleared.` : `${model} \u2192 ${result.fallbacks.join(" \u2192 ")}`
+      );
+      for (const warning of result.warnings) console.log(`  \u26A0  ${warning}`);
+      return;
+    }
+    case "show":
+    default: {
+      const { results } = await db.prepare(
+        `SELECT m.id,
+                  COALESCE(group_concat(f.fallback_model, ' \u2192 '), '') AS chain
+             FROM models m
+             JOIN upstreams u ON u.id = m.upstream_id
+             LEFT JOIN (SELECT model, fallback_model FROM model_fallbacks ORDER BY position) f
+               ON f.model = m.id
+            WHERE m.enabled = 1 AND u.enabled = 1
+            GROUP BY m.id
+            ORDER BY m.id`
+      ).all();
+      const without = results.filter((row) => row.chain === "");
+      for (const row of results) {
+        console.log(`${row.id.padEnd(55)} ${row.chain || "\u2014"}`);
+      }
+      console.log(`
+${results.length - without.length} of ${results.length} model(s) have a fallback chain.`);
+      if (without.length > 0) {
+        console.log(`A model with none answers its provider's 429, 5xx or expired credential straight to the caller (#237).`);
+      }
+      return;
+    }
+  }
+});

package/dist/keys-FWPQPMTW.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// Built by packages/cli/build.ts.
+import {
+  listFlag
+} from "./chunk-WS6NFRIU.mjs";
+import {
+  issueKey,
+  rateLimitProblem,
+  revokeKey
+} from "./chunk-2FB2T3UI.mjs";
+import {
+  CACHE_POOLS,
+  DEFAULT_CACHE_POOL,
+  isCachePool
+} from "./chunk-T3ICD43U.mjs";
+import "./chunk-LALZUKEC.mjs";
+import {
+  keyEnvironmentFor
+} from "./chunk-5TVD3ZAI.mjs";
+import {
+  connect,
+  environmentOf,
+  optionalNumber,
+  parseArgs,
+  requireString,
+  run
+} from "./chunk-7NQHBXVZ.mjs";
+import "./chunk-JZPUTXM7.mjs";
+
+// scripts/keys.ts
+run(async () => {
+  const [command, ...rest] = process.argv.slice(2);
+  const args = parseArgs(rest);
+  const environment = environmentOf(args);
+  const db = connect(environment);
+  switch (command) {
+    case "issue": {
+      const project = requireString(args, "project");
+      const allowedModels = listFlag(args.models, "models") ?? [];
+      const allowedClasses = listFlag(args.classes, "classes") ?? [];
+      const cachePool = args["cache-pool"] === void 0 ? DEFAULT_CACHE_POOL : args["cache-pool"];
+      if (!isCachePool(cachePool)) {
+        throw new Error(`--cache-pool must be one of: ${CACHE_POOLS.join(", ")}. Leave it out for '${DEFAULT_CACHE_POOL}'.`);
+      }
+      const rateLimitPerMin = optionalNumber(args, "rate-limit");
+      const accountRateLimitPerMin = optionalNumber(args, "account-rate-limit");
+      for (const [what, value] of [
+        ["--rate-limit", rateLimitPerMin],
+        ["--account-rate-limit", accountRateLimitPerMin]
+      ]) {
+        if (args[what.slice(2)] === void 0) continue;
+        const problem = rateLimitProblem(value, what);
+        if (problem !== null) throw new Error(problem);
+      }
+      const owner = await db.prepare(`SELECT tenant_id FROM projects WHERE id = ?`).bind(project).first();
+      if (owner === null) throw new Error(`No such project: ${project}`);
+      const issued = await issueKey(db, {
+        projectId: project,
+        tenantId: owner.tenant_id,
+        // The same answer the route gives (#326): production issues `live`,
+        // the demo `demo`, and anything else `test`. This line was the binary
+        // `keyEnvironmentFor` replaced in `admin-keys.ts`, still here — so
+        // `key:issue --env demo` minted a `cru_test_` key into the demo's
+        // database, contradicting the rule `openapi.ts` publishes (#328).
+        environment: keyEnvironmentFor(environment),
+        actor: requireString(args, "actor"),
+        ...typeof args.name === "string" ? { name: args.name } : {},
+        allowedModels,
+        allowedClasses,
+        rateLimitPerMin,
+        accountRateLimitPerMin,
+        conformance: args.conformance === true,
+        cachePool
+      });
+      const scope = (entries) => entries.length === 0 ? "unrestricted" : entries.join(", ");
+      console.log(`
+  environment  ${environment}`);
+      console.log(`  project      ${project}`);
+      console.log(`  models       ${scope(allowedModels)}`);
+      console.log(`  classes      ${scope(allowedClasses)}`);
+      console.log(`  cache pool   ${cachePool}`);
+      const perMin = (n) => n === null ? "none" : `${n}/min`;
+      console.log(`  rate limit   ${perMin(issued.rateLimitPerMin)}`);
+      console.log(`  acct limit   ${perMin(issued.accountRateLimitPerMin)}`);
+      console.log(`  prefix       ${issued.prefix}`);
+      console.log(`
+  ${issued.key}
+`);
+      console.log("  Shown once. It is not stored and cannot be recovered \u2014 reissue instead.\n");
+      break;
+    }
+    case "revoke": {
+      const prefix = requireString(args, "prefix");
+      const owner = await db.prepare(`SELECT p.tenant_id FROM virtual_keys k JOIN projects p ON p.id = k.project_id WHERE k.prefix = ?`).bind(prefix).first();
+      const changed = owner !== null && await revokeKey(db, {
+        tenantId: owner.tenant_id,
+        prefix,
+        actor: requireString(args, "actor"),
+        reason: requireString(args, "reason")
+      });
+      console.log(changed ? `revoked ${prefix}` : `no change \u2014 ${prefix} is unknown or already revoked`);
+      break;
+    }
+    case "list": {
+      const { results } = await db.prepare(
+        // The limit beside the pool, for the same reason the HTTP listing
+        // carries it: on the demo every key holds one nobody typed (#328),
+        // and a listing that omits it is an audit that cannot see the one
+        // field the deployment set. Raised in review of PR #338.
+        `SELECT k.prefix, p.slug, k.name, k.created_at, k.revoked_at, k.cache_pool, k.rate_limit_per_min
+             FROM virtual_keys k JOIN projects p ON p.id = k.project_id
+            ORDER BY k.created_at DESC`
+      ).all();
+      if (results.length === 0) console.log("no keys issued");
+      for (const row of results) {
+        const limit = row.rate_limit_per_min === null ? "none" : `${row.rate_limit_per_min}/min`;
+        console.log(
+          `${row.prefix}  ${row.slug.padEnd(8)} ${(row.revoked_at ? "revoked" : "active").padEnd(8)} ${row.cache_pool.padEnd(8)} ${limit.padEnd(8)} ${row.name ?? ""}`
+        );
+      }
+      break;
+    }
+    default:
+      console.error("usage: issue | revoke | list  (see scripts/keys.ts)");
+      process.exitCode = 1;
+  }
+});

package/dist/ledger-XBGWXY6C.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Built by packages/cli/build.ts.
+import {
+  compressionBySession,
+  compressionSavings,
+  savedShare
+} from "./chunk-HQDQTXRX.mjs";
+import {
+  effectiveRates,
+  spendBy
+} from "./chunk-XOH3XKM3.mjs";
+import "./chunk-BNP63KB2.mjs";
+import "./chunk-SYTYOTO4.mjs";
+import "./chunk-O7TNRKSA.mjs";
+import "./chunk-T3ICD43U.mjs";
+import {
+  formatUsd
+} from "./chunk-THEXUHQC.mjs";
+import "./chunk-5TVD3ZAI.mjs";
+import {
+  connect,
+  environmentOf,
+  parseArgs,
+  run
+} from "./chunk-7NQHBXVZ.mjs";
+import "./chunk-JZPUTXM7.mjs";
+
+// scripts/ledger.ts
+run(async () => {
+  const args = parseArgs(process.argv.slice(2));
+  const db = connect(environmentOf(args));
+  const month = typeof args.month === "string" ? args.month : (/* @__PURE__ */ new Date()).toISOString().slice(0, 7);
+  if (args.rates === true) {
+    const rows2 = await effectiveRates(db, month);
+    if (rows2.length === 0) return console.log(`no priced requests in ${month}`);
+    console.log(`effective rate vs table rate, ${month}
+`);
+    console.log("model                                      reqs   observed/Mtok   table in/Mtok");
+    for (const r of rows2) {
+      const observed = r.observedInputMicrosPerMtok;
+      const table = r.tableInputMicrosPerMtok;
+      const drift = observed !== null && table !== null && table > 0 ? `  (${((observed - table) / table * 100).toFixed(0)}%)` : "";
+      console.log(
+        `${r.model.slice(0, 40).padEnd(42)} ${String(r.requests).padStart(4)}   ${(observed === null ? "-" : formatUsd(observed, 4)).padStart(13)}   ${(table === null ? "-" : formatUsd(table, 4)).padStart(13)}${drift}`
+      );
+    }
+    console.log("\nObserved blends input and output, so it is not comparable to the table rate");
+    console.log("directly \u2014 a change in the ratio over time is the signal, not the level.");
+    return;
+  }
+  if (typeof args.session === "string") {
+    const rows2 = await compressionBySession(db, args.session);
+    if (rows2.length === 0) return console.log(`no ledger entries for session ${args.session}`);
+    console.log(`session ${args.session}
+`);
+    console.log("project                                     reqs   ran  applied      before       after   saved        spend");
+    for (const r of rows2) {
+      const saved = savedShare(r);
+      console.log(
+        `${r.projectId.slice(0, 42).padEnd(44)}${String(r.requests).padStart(4)}  ${String(r.ran).padStart(4)}  ${String(r.applied).padStart(7)}  ${String(r.bytesBefore).padStart(10)}  ${String(r.bytesAfter).padStart(10)}  ${(saved === null ? "-" : `${(saved * 100).toFixed(1)}%`).padStart(6)}  ${formatUsd(r.micros, 4).padStart(11)}`
+      );
+      console.log(`${"".padEnd(44)}${r.first} \u2192 ${r.last}`);
+    }
+    return;
+  }
+  if (args.compression === true) {
+    const rows2 = await compressionSavings(db, month);
+    if (rows2.length === 0) return console.log(`compression did not run in ${month}`);
+    console.log(`request compression, ${month}
+`);
+    console.log("project                                     reqs  applied      before       after   saved");
+    for (const r of rows2) {
+      const saved = savedShare(r);
+      console.log(
+        `${r.projectId.slice(0, 42).padEnd(44)}${String(r.requests).padStart(4)}  ${String(r.applied).padStart(7)}  ${String(r.bytesBefore).padStart(10)}  ${String(r.bytesAfter).padStart(10)}  ${(saved === null ? "-" : `${(saved * 100).toFixed(1)}%`).padStart(6)}`
+      );
+    }
+    return;
+  }
+  const dimension = typeof args.by === "string" ? args.by : "project_id";
+  const rows = await spendBy(db, dimension, month);
+  if (rows.length === 0) return console.log(`no ledger entries in ${month}`);
+  console.log(`spend by ${dimension}, ${month}
+`);
+  const byComponent = dimension === "component";
+  console.log(`${dimension.padEnd(44)} reqs  ${byComponent ? "     units" : "    tokens"}        spend`);
+  let totalMicros = 0;
+  let totalRequests = 0;
+  for (const row of rows) {
+    totalMicros += row.micros;
+    totalRequests += row.requests;
+    console.log(
+      `${String(row.bucket ?? "-").slice(0, 42).padEnd(44)} ${String(row.requests).padStart(4)}  ${String(byComponent ? row.units ?? 0 : row.tokens).padStart(10)}  ${formatUsd(row.micros, 4).padStart(11)}`
+    );
+  }
+  console.log(`${"".padEnd(44)} ${String(totalRequests).padStart(4)}  ${"".padStart(10)}  ${formatUsd(totalMicros, 4).padStart(11)}`);
+});

package/dist/member-ZBV4YG2M.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Built by packages/cli/build.ts.
+import {
+  ROLES,
+  grantMembership,
+  listMemberships,
+  revokeMembership
+} from "./chunk-2NVDAK5J.mjs";
+import {
+  connect,
+  environmentOf,
+  parseArgs,
+  requireString,
+  run
+} from "./chunk-7NQHBXVZ.mjs";
+import "./chunk-JZPUTXM7.mjs";
+
+// scripts/member.ts
+run(async () => {
+  const [command, ...rest] = process.argv.slice(2);
+  const args = parseArgs(rest);
+  const db = connect(environmentOf(args));
+  const tenant = typeof args.tenant === "string" ? args.tenant : "bytesbrains";
+  switch (command) {
+    case "grant": {
+      const role = typeof args.role === "string" ? args.role : "viewer";
+      if (!ROLES.includes(role)) throw new Error(`--role must be one of: ${ROLES.join(", ")}`);
+      const uid = requireString(args, "uid");
+      await grantMembership(db, uid, tenant, role, requireString(args, "actor"));
+      console.log(`granted ${role} on ${tenant} to ${uid}`);
+      break;
+    }
+    case "revoke": {
+      const uid = requireString(args, "uid");
+      const outcome = await revokeMembership(
+        db,
+        uid,
+        tenant,
+        requireString(args, "actor"),
+        requireString(args, "reason")
+      );
+      switch (outcome) {
+        case "revoked":
+          console.log(`revoked membership of ${uid}`);
+          break;
+        case "not_found":
+          console.log(`no change \u2014 ${uid} was not a member`);
+          break;
+        case "last_owner":
+          console.log(`refused \u2014 ${uid} is the last owner of ${tenant}. Grant another owner first.`);
+          process.exitCode = 1;
+          break;
+      }
+      break;
+    }
+    case "list": {
+      const members = await listMemberships(db, typeof args.tenant === "string" ? tenant : void 0);
+      if (members.length === 0) {
+        console.log("no memberships. Nobody can call the control plane until one exists.");
+        break;
+      }
+      console.log("uid                                       tenant        role     granted by");
+      for (const m of members) {
+        console.log(
+          `${m.uid.slice(0, 40).padEnd(42)}${m.tenantId.padEnd(14)}${m.role.padEnd(9)}${m.createdBy ?? "-"}`
+        );
+      }
+      break;
+    }
+    default:
+      console.error("usage: grant | revoke | list  (see scripts/member.ts)");
+      process.exitCode = 1;
+  }
+});