create-quorum-router 0.1.5 → 0.1.7

package/README.md

@@ -13,9 +13,10 @@ cd my-quorum-router-demo
 deno --version
 deno task smoke
 deno task intake
+deno task supabase:status
 ```
 
-Current package version: `create-quorum-router@0.1.5`. Releases are published
+Current package version: `create-quorum-router@0.1.7`. Releases are published
 from an immutable Git tag through GitHub Actions OIDC Trusted Publishing.
 
 ## What the generated project supports
@@ -63,6 +64,19 @@ preferred public dogfood path.
 Do not commit `.env`, `router.config.local.json`, `.quorum-router/`, or `out/`.
 Do not paste tokens into chat/logs.
 
+## Optional user-owned Supabase audit
+
+The generated project works without Supabase. Audit defaults to `disabled`.
+Users who opt in apply the generated migration to a Supabase project they own,
+choose `optional` or `required` in the non-secret feature config, inject a
+project URL, publishable/anon key, and Supabase Auth session JWT at runtime, and
+run `deno task supabase:status` before routing.
+
+The runtime rejects service-role/admin credentials. Audit records exclude
+prompts, model responses, credentials, client-supplied actor/org identity, and
+client timestamps. Agent Bus, Realtime, state sync, and analytics dashboards are
+not part of this integration.
+
 ## Runtime boundaries
 
 - Best Route/direct is production-ready best-answer routing.
@@ -71,7 +85,7 @@ Do not paste tokens into chat/logs.
   slice only when separately configured with signed policy and distinct
   approval.
 - The generated scaffold does not enable mutation by default.
-- No service-role runtime.
+- No service-role/admin runtime credentials.
 - No live Supabase Agent Bus runtime writes.
 - Public launch requires the repository verification, package tarball, registry
   readback, and clean-room NPX scaffold checks to pass.

package/bin/create-quorum-router.js

@@ -3,7 +3,7 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
-const VERSION = "0.1.5";
+const VERSION = "0.1.7";
 const SUPPORTED_TEMPLATES = new Set(["basic"]);
 
 function usage() {
@@ -56,13 +56,33 @@ function parseArgs(argv) {
   return options;
 }
 
-function copyRecursive(from, to) {
+function rejectSymlink(destination) {
+  try {
+    if (fs.lstatSync(destination).isSymbolicLink()) {
+      throw new Error(`refusing to write through symlink: ${destination}`);
+    }
+  } catch (error) {
+    if (error && error.code === "ENOENT") return;
+    throw error;
+  }
+}
+
+function copyRecursive(from, to, targetRoot) {
+  const relative = path.relative(targetRoot, to);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`refusing to write outside target directory: ${to}`);
+  }
+  rejectSymlink(to);
   const stat = fs.statSync(from);
   if (stat.isDirectory()) {
     fs.mkdirSync(to, { recursive: true });
     for (const entry of fs.readdirSync(from)) {
       const targetEntry = entry === "gitignore" ? ".gitignore" : entry;
-      copyRecursive(path.join(from, entry), path.join(to, targetEntry));
+      copyRecursive(
+        path.join(from, entry),
+        path.join(to, targetEntry),
+        targetRoot,
+      );
     }
     return;
   }
@@ -97,6 +117,7 @@ function main() {
   }
 
   const targetDir = path.resolve(process.cwd(), parsed.dir);
+  rejectSymlink(targetDir);
   if (isNonEmptyDirectory(targetDir) && !parsed.force) {
     throw new Error(
       `refusing to overwrite non-empty directory: ${targetDir}\n` +
@@ -106,7 +127,7 @@ function main() {
 
   const templateDir = path.join(__dirname, "..", "templates", parsed.template);
   fs.mkdirSync(targetDir, { recursive: true });
-  copyRecursive(templateDir, targetDir);
+  copyRecursive(templateDir, targetDir, targetDir);
   fs.mkdirSync(path.join(targetDir, "out"), { recursive: true });
   fs.writeFileSync(path.join(targetDir, "out", ".gitkeep"), "");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quorum-router",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Create a local QuorumRouter project.",
   "license": "MIT",
   "bin": {

package/templates/basic/README.md

@@ -1,7 +1,7 @@
 # QuorumRouter generated workspace
 
 This generated workspace contains the MIT-licensed QuorumRouter current release.
-npm latest targets v0.1.5.
+npm latest targets v0.1.7.
 
 QuorumRouter is **MIT**. It is **open source**. Commercial and production use
 are permitted under the MIT License.
@@ -19,8 +19,10 @@ are permitted under the MIT License.
 - Conversation-only `agent_chat` is explicit opt-in.
 - SafeLoop-backed production repository execution is not enabled by this
   generated scaffold; it requires external signed policy and distinct approval.
-- No service-role runtime.
-- No live Supabase runtime writes.
+- No service-role runtime; service-role/admin credentials are rejected even when
+  audit is disabled.
+- BYO Supabase audit is disabled by default and writes only when explicitly set
+  to `optional` or `required`.
 - No live Supabase Agent Bus runtime writes.
 - Best Route/direct is the production-ready best-answer routing path.
 - `agent-chat` is read-only explicit opt-in only.
@@ -39,6 +41,7 @@ deno task intake
 deno task auth:status
 deno task models:list
 deno task health
+deno task supabase:status
 ```
 
 `smoke` proves the local scaffold runs with deterministic fixtures only. It does
@@ -51,6 +54,37 @@ under `out/`, and recommends the next command.
 In short: intake is the first real setup command before `route:once`,
 `best-route`, or read-only `agent-chat`.
 
+## Optional BYO Supabase audit
+
+Supabase is not required. With no Supabase config or env, every existing task
+keeps its prior behavior and `deno task supabase:status` exits successfully with
+`state: disabled` without making a network request.
+
+To persist route outcomes in a Supabase project you own:
+
+1. Create or choose your Supabase project.
+2. Apply **both** files under `supabase/migrations/` in filename order using an
+   admin context outside the router runtime. The later limits migration is
+   mandatory.
+3. Ensure the active Supabase Auth user session JWT has an authenticated `sub`.
+4. Copy `router.config.example.json` to `router.config.json` and set only
+   `features.supabase.audit.mode` to `optional` or `required`.
+5. Inject `QUORUM_ROUTER_SUPABASE_URL`, `QUORUM_ROUTER_SUPABASE_ANON_KEY`, and
+   `QUORUM_ROUTER_SUPABASE_SESSION_JWT` at runtime.
+6. Run `deno task supabase:status`, then run `route:once` or `best-route`.
+
+`optional` preserves a successful route and prints a warning when audit delivery
+fails. `required` withholds the route result and exits nonzero when audit
+delivery fails. The RPC receives only the route decision and bounded metadata.
+It never receives prompts, model responses, credentials, `org_id`, `actor_id`,
+or `created_at`; the database derives both the actor and this single-user BYO
+audit namespace from `auth.uid()` and owns the timestamp. There is no central or
+shared database and no client tenant claim.
+
+Runtime service-role/admin credentials are forbidden. Agent Bus, Realtime
+wakeup, state sync, and an analytics dashboard are future features and are not
+enabled by this audit integration.
+
 ## Real provider dogfood commands
 
 Run only after `intake` reports a usable OAuth/session/wrapper provider:
@@ -87,6 +121,25 @@ Behavior:
   Only use this with repositories you are allowed to send to the selected
   provider.
 
+### Cost-aware Best Route
+
+Cost-aware routing is disabled unless both budget variables are set. Estimates
+are user-supplied per invocation, not live provider billing data.
+
+```bash
+QUORUM_ROUTER_MAX_BUDGET_USD=0.05 \
+QUORUM_ROUTER_ESTIMATED_COSTS_JSON='{"openai/gpt-5":0.03,"xai/grok":0.02}' \
+RUN_EXTERNAL_MODEL_DOGFOOD=1 \
+  deno task best-route --prompt "Choose the safest launch copy."
+```
+
+Best Route preserves candidate quality/readiness order, admits candidates while
+their configured estimates fit the budget, and records selected and excluded
+model IDs plus reasons in `out/best-route-trace.json`. Models without an
+estimate are excluded when cost-aware routing is enabled. If no candidate fits,
+the command fails before invoking a provider. This is pre-invocation budget
+control; it does not claim exact or live API spend.
+
 ### Forced wrapper provider/model selection
 
 Use these only when you want a specific local wrapper/model. The scaffold fails
@@ -152,17 +205,22 @@ not paste them into chat/logs and do not commit `.env`.
 - `.gitignore` — excludes `.env`, `out/`, `router.config.local.json`,
   `provider_config.json`, and `.quorum-router/`.
 - `router.config.example.json` — non-secret example boundaries.
+- `supabase/migrations/20260701130000_workflow_access_audit.sql` — optional BYO
+  Supabase audit migration
+- `supabase/migrations/20260712211500_workflow_access_audit_limits.sql` —
+  required RPC narrowing and payload-limit migration
 - `src/cli.ts` — command dispatcher.
+- `src/supabase.ts` — offline status and selective audit RPC hook.
 - `src/intake.ts` — first-run onboarding.
 - `src/auth.ts`, `src/auth_oauth.ts`, `src/auth_session.ts`,
   `src/auth_env_fallback.ts` — auth/session/fallback boundaries.
 - `src/provider_registry.ts`, `src/model_inventory.ts`, `src/wrapper_client.ts`,
   `src/provider_client.ts` — provider discovery and safe invocation.
 - `src/best_route.ts`, `src/agent_chat.ts` — gated dogfood commands.
+- `src/cost_aware.ts` — estimated-cost budget selection for Best Route.
 - `src/trace.ts`, `src/redact.ts`, `src/schema.ts`, `src/fixture_smoke.ts` —
   trace/redaction/schema/fixture support.
 - `out/.gitkeep` — local output directory placeholder.
 
-Public Product Hunt/X launch remains blocked until the user personally runs a
-local pre-release workspace and approves release continuation. This scaffold
-does not publish npm, create a GitHub release, or mutate tags/dist-tags.
+This generated scaffold operates locally. It does not publish npm packages,
+create GitHub releases, or mutate tags or dist-tags.

package/templates/basic/deno.json

@@ -12,6 +12,7 @@
     "auth:logout": "deno run --allow-read --allow-write --allow-env src/cli.ts auth:logout",
     "models:list": "deno run --allow-read --allow-write --allow-env --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts models:list",
     "health": "deno run --allow-read --allow-write --allow-env --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts health",
+    "supabase:status": "deno run --allow-read --allow-env src/cli.ts supabase:status",
     "route:once": "deno run --allow-read --allow-write --allow-env --allow-net --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts route:once",
     "best-route": "deno run --allow-read --allow-write --allow-env --allow-net --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts best-route",
     "agent-chat": "deno run --allow-read --allow-write --allow-env --allow-net --allow-run=grok,codex,claude,gemini,qwen,devin src/cli.ts agent-chat"

package/templates/basic/router.config.example.json

@@ -5,6 +5,17 @@
     "enabled_by": "QUORUM_ROUTER_AUTH_MODE=env",
     "usage": "private manual fallback only"
   },
+  "features": {
+    "supabase": {
+      "audit": {
+        "mode": "disabled"
+      }
+    }
+  },
+  "cost_aware": {
+    "enabled_by": "QUORUM_ROUTER_MAX_BUDGET_USD + QUORUM_ROUTER_ESTIMATED_COSTS_JSON",
+    "pricing_source": "user-supplied estimates, not live billing"
+  },
   "runtime_boundaries": {
     "best_route_direct": "production-ready best-answer routing",
     "agent_chat": "experimental explicit opt-in only",

package/templates/basic/src/auth_session.ts

@@ -88,6 +88,7 @@ export function discoverInventory(
       can_invoke: exists,
       command: spec.command,
       args_template: spec.args_template,
+      prompt_transport: spec.prompt_transport,
       notes: exists
         ? [
           ...spec.notes,

package/templates/basic/src/best_route.ts

@@ -21,6 +21,7 @@ import {
 import { buildTrace, score, writeTrace } from "./trace.ts";
 import { callWrapper } from "./wrapper_client.ts";
 import { preparePromptWithContext } from "./context.ts";
+import { selectCandidatesWithinBudget } from "./cost_aware.ts";
 
 function hasExplicitSelection(request: ProviderSelectionRequest): boolean {
   return Boolean(
@@ -261,7 +262,12 @@ export async function runBestRoute(
 > {
   assertOptIn();
   const authMode = parseAuthMode(readRouterEnv("QUORUM_ROUTER_AUTH_MODE"));
-  const { request, candidates } = await discoverCandidates(authMode);
+  const { request, candidates: discoveredCandidates } =
+    await discoverCandidates(
+      authMode,
+    );
+  const costAwareDecision = selectCandidatesWithinBudget(discoveredCandidates);
+  const candidates = costAwareDecision.candidates;
   if (candidates.length === 0) {
     throw new Error(
       "OAuth/session-first provider unavailable. best-route has no usable OAuth/session/wrapper provider yet. Next: deno task auth:login",
@@ -316,6 +322,9 @@ export async function runBestRoute(
       selectionHonored(request, result)
     ),
     fallbackUsed: usedEnvFallback,
+    costAware: costAwareDecision.cost.enabled
+      ? costAwareDecision.cost
+      : undefined,
   });
   const tracePath = await writeTrace("best-route-trace", trace);
   return { results, tracePath, trace };

package/templates/basic/src/cli.ts

@@ -11,6 +11,11 @@ import {
 } from "./model_inventory.ts";
 import { redact, summarize } from "./redact.ts";
 import { parseAuthMode } from "./schema.ts";
+import {
+  auditRouteOutcome,
+  preflightRequiredSupabaseAudit,
+  runSupabaseStatus,
+} from "./supabase.ts";
 import { buildTrace, writeTrace } from "./trace.ts";
 
 const DEFAULT_PROMPT = "Review this README for risky claims.";
@@ -22,6 +27,7 @@ type CommandName =
   | "auth:logout"
   | "models:list"
   | "health"
+  | "supabase:status"
   | "route:once"
   | "best-route"
   | "agent-chat";
@@ -32,11 +38,12 @@ function commandName(): CommandName {
     command === "intake" || command === "auth:status" ||
     command === "auth:login" || command === "auth:logout" ||
     command === "models:list" || command === "health" ||
+    command === "supabase:status" ||
     command === "route:once" || command === "best-route" ||
     command === "agent-chat"
   ) return command;
   throw new Error(
-    "usage: deno task intake|auth:status|auth:login|auth:logout|models:list|health|route:once|best-route|agent-chat",
+    "usage: deno task intake|auth:status|auth:login|auth:logout|models:list|health|supabase:status|route:once|best-route|agent-chat",
   );
 }
 
@@ -101,10 +108,13 @@ try {
   else if (command === "auth:logout") await runAuthLogout();
   else if (command === "models:list") await runModelsList();
   else if (command === "health") await runHealth();
+  else if (command === "supabase:status") await runSupabaseStatus();
   else if (command === "route:once") {
+    await preflightRequiredSupabaseAudit();
     const { results, tracePath, trace } = await invokeSelected(
       promptFromArgs(),
     );
+    await auditRouteOutcome(trace);
     console.log("QuorumRouter route:once");
     console.log(`provider: ${results[0].provider}`);
     console.log(`model: ${results[0].model}`);
@@ -116,7 +126,9 @@ try {
     console.log(`final: ${summarize(results[0].response_summary, 500)}`);
     console.log(`trace: ${tracePath}`);
   } else if (command === "best-route") {
-    const { results, tracePath } = await runBestRoute(promptFromArgs());
+    await preflightRequiredSupabaseAudit();
+    const { results, tracePath, trace } = await runBestRoute(promptFromArgs());
+    await auditRouteOutcome(trace);
     console.log("QuorumRouter best-route");
     console.log(`models_called: ${results.length}`);
     console.log(`trace: ${tracePath}`);

package/templates/basic/src/cost_aware.ts

@@ -0,0 +1,150 @@
+import { readRouterEnv } from "./env.ts";
+import type { CostAwareTrace, ModelInventoryEntry } from "./schema.ts";
+
+export type CostExclusion = {
+  model_id: string;
+  estimated_cost_usd?: number;
+  reason: "missing_estimate" | "budget_exceeded";
+};
+
+export type CostAwareSelection =
+  | CostAwareTrace
+  | {
+    enabled: false;
+    selected_model_ids: string[];
+    excluded: CostExclusion[];
+  };
+
+export type CostAwareConfig = {
+  maxBudgetUsd: number;
+  estimates: Map<string, number>;
+};
+
+function normalizedModelId(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function parsePositiveBudget(raw: string): number {
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(
+      "QuorumRouter blocked: QUORUM_ROUTER_MAX_BUDGET_USD must be a finite number > 0",
+    );
+  }
+  return value;
+}
+
+function parseEstimates(raw: string): Map<string, number> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      "QuorumRouter blocked: QUORUM_ROUTER_ESTIMATED_COSTS_JSON must be valid JSON",
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(
+      "QuorumRouter blocked: QUORUM_ROUTER_ESTIMATED_COSTS_JSON must be a model-id to USD object",
+    );
+  }
+
+  const estimates = new Map<string, number>();
+  for (const [rawModelId, rawCost] of Object.entries(parsed)) {
+    const modelId = normalizedModelId(rawModelId);
+    if (
+      !modelId || typeof rawCost !== "number" || !Number.isFinite(rawCost) ||
+      rawCost < 0
+    ) {
+      throw new Error(
+        "QuorumRouter blocked: every cost estimate must use a non-empty model id and a finite USD number >= 0",
+      );
+    }
+    if (estimates.has(modelId)) {
+      throw new Error(
+        `QuorumRouter blocked: duplicate normalized cost estimate for ${modelId}`,
+      );
+    }
+    estimates.set(modelId, rawCost);
+  }
+  if (estimates.size === 0) {
+    throw new Error(
+      "QuorumRouter blocked: QUORUM_ROUTER_ESTIMATED_COSTS_JSON must contain at least one estimate",
+    );
+  }
+  return estimates;
+}
+
+export function readCostAwareConfig(): CostAwareConfig | undefined {
+  const rawBudget = readRouterEnv("QUORUM_ROUTER_MAX_BUDGET_USD");
+  const rawEstimates = readRouterEnv("QUORUM_ROUTER_ESTIMATED_COSTS_JSON");
+  if (rawBudget === undefined && rawEstimates === undefined) return undefined;
+  if (rawBudget === undefined || rawEstimates === undefined) {
+    throw new Error(
+      "QuorumRouter blocked: cost-aware routing requires both QUORUM_ROUTER_MAX_BUDGET_USD and QUORUM_ROUTER_ESTIMATED_COSTS_JSON",
+    );
+  }
+  return {
+    maxBudgetUsd: parsePositiveBudget(rawBudget),
+    estimates: parseEstimates(rawEstimates),
+  };
+}
+
+export function selectCandidatesWithinBudget(
+  candidates: ModelInventoryEntry[],
+  config = readCostAwareConfig(),
+): { candidates: ModelInventoryEntry[]; cost: CostAwareSelection } {
+  if (!config) {
+    return {
+      candidates,
+      cost: {
+        enabled: false,
+        selected_model_ids: candidates.map((candidate) => candidate.model_id),
+        excluded: [],
+      },
+    };
+  }
+
+  const selected: ModelInventoryEntry[] = [];
+  const excluded: CostExclusion[] = [];
+  let estimatedTotalUsd = 0;
+  for (const candidate of candidates) {
+    const estimate = config.estimates.get(
+      normalizedModelId(candidate.model_id),
+    );
+    if (estimate === undefined) {
+      excluded.push({
+        model_id: candidate.model_id,
+        reason: "missing_estimate",
+      });
+      continue;
+    }
+    if (estimatedTotalUsd + estimate > config.maxBudgetUsd) {
+      excluded.push({
+        model_id: candidate.model_id,
+        estimated_cost_usd: estimate,
+        reason: "budget_exceeded",
+      });
+      continue;
+    }
+    selected.push(candidate);
+    estimatedTotalUsd += estimate;
+  }
+
+  if (selected.length === 0) {
+    throw new Error(
+      "QuorumRouter blocked: cost-aware routing selected no candidates within the configured budget",
+    );
+  }
+  return {
+    candidates: selected,
+    cost: {
+      enabled: true,
+      pricing_source: "configured_estimate_not_live_billing",
+      max_budget_usd: config.maxBudgetUsd,
+      estimated_total_usd: estimatedTotalUsd,
+      selected_model_ids: selected.map((candidate) => candidate.model_id),
+      excluded,
+    },
+  };
+}

package/templates/basic/src/provider_registry.ts

@@ -9,6 +9,7 @@ export type ProviderSpec = {
   source: "wrapper" | "oauth_session" | "local_cli" | "env_fallback";
   command?: string;
   args_template?: string[];
+  prompt_transport?: "stdin" | "file";
   list_models_args?: string[];
   list_blocked_reason?: string;
   notes: string[];
@@ -145,8 +146,9 @@ export const LOCAL_PROVIDER_SPECS: ProviderSpec[] = [
       "__CWD__",
       "--output-last-message",
       "__OUT__",
-      "__PROMPT__",
+      "-",
     ],
+    prompt_transport: "stdin",
     list_blocked_reason:
       "codex models is tty/stdin dependent in this environment; model catalog listing is unavailable from non-interactive Deno.",
     notes: [
@@ -160,7 +162,8 @@ export const LOCAL_PROVIDER_SPECS: ProviderSpec[] = [
     auth_mode: "oauth",
     source: "oauth_session",
     command: "claude",
-    args_template: ["-p", "__PROMPT__"],
+    args_template: ["-p"],
+    prompt_transport: "stdin",
     list_blocked_reason:
       "Claude Code model listing is blocked by organization policy / disabled subscription access in this environment.",
     notes: [
@@ -174,7 +177,8 @@ export const LOCAL_PROVIDER_SPECS: ProviderSpec[] = [
     auth_mode: "oauth",
     source: "oauth_session",
     command: "gemini",
-    args_template: ["-p", "__PROMPT__"],
+    args_template: ["-p", ""],
+    prompt_transport: "stdin",
     list_blocked_reason:
       "Gemini CLI list/invoke paths require a trusted directory in non-interactive runs unless the user opts into the trust setting.",
     notes: [
@@ -189,14 +193,15 @@ export const LOCAL_PROVIDER_SPECS: ProviderSpec[] = [
     source: "oauth_session",
     command: "grok",
     args_template: [
-      "-p",
-      "__PROMPT__",
+      "--prompt-file",
+      "__PROMPT_FILE__",
       "--output-format",
       "plain",
       "--permission-mode",
       "plan",
       "--disable-web-search",
     ],
+    prompt_transport: "file",
     list_models_args: ["models"],
     notes: [
       "Uses existing Grok CLI session; `grok models` is safe list-only discovery.",
@@ -209,7 +214,8 @@ export const LOCAL_PROVIDER_SPECS: ProviderSpec[] = [
     auth_mode: "session",
     source: "local_cli",
     command: "devin",
-    args_template: ["-p", "__PROMPT__"],
+    args_template: ["-p", "--prompt-file", "__PROMPT_FILE__"],
+    prompt_transport: "file",
     list_blocked_reason:
       "Devin CLI does not expose a models subcommand in this environment.",
     notes: ["Uses existing Devin CLI session."],
@@ -221,7 +227,8 @@ export const LOCAL_PROVIDER_SPECS: ProviderSpec[] = [
     auth_mode: "session",
     source: "local_cli",
     command: "qwen",
-    args_template: ["-p", "__PROMPT__"],
+    args_template: ["-p", ""],
+    prompt_transport: "stdin",
     list_blocked_reason:
       "Qwen CLI model listing path is stdin/API-key dependent in this environment.",
     notes: ["Uses existing local Qwen CLI session."],