create-quorum-router 0.1.5

package/templates/basic/src/agent_chat.ts

@@ -0,0 +1,262 @@
+import {
+  discoverInventoryWithModelListing,
+  invokableEntries,
+} from "./auth_session.ts";
+import { callEnvFallback } from "./auth_env_fallback.ts";
+import { preparePromptWithContext } from "./context.ts";
+import { readRouterEnv } from "./env.ts";
+import { redact, summarize } from "./redact.ts";
+import { readProviderSelectionRequest } from "./provider_registry.ts";
+import {
+  type AgentChatTurn,
+  assertAgentChatOptIn,
+  assertOptIn,
+  type ModelInventoryEntry,
+  parseAuthMode,
+  type ProviderResult,
+} from "./schema.ts";
+import { selectInvokableCandidates, selectionHonored } from "./best_route.ts";
+import { buildTrace, writeTrace } from "./trace.ts";
+import { callWrapper } from "./wrapper_client.ts";
+
+const DEFAULT_MAX_TURNS = 6;
+const MAX_ALLOWED_TURNS = 12;
+const MAX_TRANSCRIPT_CHARS = 12_000;
+
+export type AgentChatProgress =
+  | { type: "start"; agents: Array<{ provider: string; model: string }> }
+  | { type: "turn"; turn: AgentChatTurn }
+  | { type: "complete"; turnCount: number };
+
+function maxTurns(): number {
+  const raw = Deno.env.get("QUORUM_ROUTER_AGENT_CHAT_MAX_TURNS")?.trim();
+  if (!raw) return DEFAULT_MAX_TURNS;
+  const parsed = Number(raw);
+  if (
+    !Number.isSafeInteger(parsed) || parsed < 2 || parsed > MAX_ALLOWED_TURNS
+  ) {
+    throw new Error(
+      `QuorumRouter blocked: QUORUM_ROUTER_AGENT_CHAT_MAX_TURNS must be an integer from 2 to ${MAX_ALLOWED_TURNS}`,
+    );
+  }
+  return parsed;
+}
+
+function distinctAgents(
+  candidates: ModelInventoryEntry[],
+): ModelInventoryEntry[] {
+  const seen = new Set<string>();
+  const distinct: ModelInventoryEntry[] = [];
+  for (const candidate of candidates) {
+    const identity =
+      `${candidate.provider.toLowerCase()}/${candidate.model.toLowerCase()}`;
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    distinct.push(candidate);
+  }
+  return distinct;
+}
+
+function transcriptText(turns: AgentChatTurn[]): string {
+  const text = turns.map((turn) =>
+    `Round ${turn.round} — ${turn.provider}/${turn.model}${
+      turn.reply_to
+        ? ` replying to ${turn.reply_to.provider}/${turn.reply_to.model}`
+        : ""
+    }:\n${turn.content}`
+  ).join("\n\n");
+  return text.length <= MAX_TRANSCRIPT_CHARS
+    ? text
+    : text.slice(text.length - MAX_TRANSCRIPT_CHARS);
+}
+
+function turnPrompt(args: {
+  originalPrompt: string;
+  turns: AgentChatTurn[];
+  speaker: ModelInventoryEntry;
+  peer: ModelInventoryEntry;
+  round: number;
+  totalRounds: number;
+}): string {
+  const prior = transcriptText(args.turns) || "No prior turns.";
+  return [
+    "You are participating in a bounded cross-model Agent Chat.",
+    `You are ${args.speaker.provider}/${args.speaker.model}.`,
+    `The other participant is ${args.peer.provider}/${args.peer.model}.`,
+    `This is round ${args.round} of ${args.totalRounds}.`,
+    "This is a text-only discussion. Do not use tools, inspect files, run commands, or modify the workspace.",
+    "Read the prior transcript. Respond directly to the other model's latest argument.",
+    "Disagree when warranted, explain why, revise your position when persuaded, and move toward a concrete conclusion.",
+    "Do not impersonate the other model. Do not add speaker labels. Keep the response under 900 characters.",
+    "",
+    `USER TASK:\n${args.originalPrompt}`,
+    "",
+    `PRIOR TRANSCRIPT:\n${prior}`,
+  ].join("\n");
+}
+
+async function invoke(
+  candidate: ModelInventoryEntry,
+  prompt: string,
+): Promise<ProviderResult> {
+  return candidate.source === "env_fallback"
+    ? await callEnvFallback(prompt)
+    : await callWrapper(candidate, prompt);
+}
+
+export async function runAgentChat(
+  prompt: string,
+  onProgress?: (progress: AgentChatProgress) => void,
+): Promise<{ tracePath: string; turns: AgentChatTurn[] }> {
+  assertAgentChatOptIn();
+  assertOptIn();
+  const authMode = parseAuthMode(readRouterEnv("QUORUM_ROUTER_AUTH_MODE"));
+  const request = readProviderSelectionRequest();
+  const inventory = await discoverInventoryWithModelListing(authMode, request);
+  const candidates = selectInvokableCandidates(
+    invokableEntries(inventory),
+    authMode,
+    request,
+    inventory.entries,
+  );
+  const candidatePool = distinctAgents(candidates);
+  if (candidatePool.length < 2) {
+    throw new Error(
+      "QuorumRouter blocked: live agent-chat requires at least two distinct invokable provider/model identities. Run `deno task models:list` and authenticate a second provider.",
+    );
+  }
+  if (!candidatePool.every((agent) => selectionHonored(request, agent))) {
+    throw new Error(
+      "QuorumRouter blocked: agent-chat provider selection was not honored",
+    );
+  }
+
+  const prepared = await preparePromptWithContext(prompt);
+  const rounds = maxTurns();
+  const agents: ModelInventoryEntry[] = [];
+  const turns: AgentChatTurn[] = [];
+  const results: ProviderResult[] = [];
+  const errors: string[] = [];
+  let announced = false;
+  const announce = () => {
+    if (announced || agents.length < 2) return;
+    announced = true;
+    onProgress?.({
+      type: "start",
+      agents: agents.map(({ provider, model }) => ({ provider, model })),
+    });
+    for (const turn of turns) onProgress?.({ type: "turn", turn });
+  };
+
+  for (let index = 0; index < rounds; index += 1) {
+    let speaker: ModelInventoryEntry;
+    let result: ProviderResult;
+    if (agents.length < 2) {
+      const unused = candidatePool.filter((candidate) =>
+        !agents.some((agent) =>
+          agent.provider === candidate.provider &&
+          agent.model === candidate.model
+        )
+      );
+      let selected: ModelInventoryEntry | undefined;
+      let selectedResult: ProviderResult | undefined;
+      for (const candidate of unused) {
+        const peer = agents.at(-1) ??
+          unused.find((entry) => entry !== candidate) ?? candidate;
+        try {
+          selectedResult = await invoke(
+            candidate,
+            turnPrompt({
+              originalPrompt: prepared.prompt,
+              turns,
+              speaker: candidate,
+              peer,
+              round: index + 1,
+              totalRounds: rounds,
+            }),
+          );
+          selected = candidate;
+          break;
+        } catch (error) {
+          errors.push(
+            `${candidate.provider}/${candidate.model}: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        }
+      }
+      if (!selected || !selectedResult) {
+        throw new Error(
+          `QuorumRouter blocked: could not establish two working Agent Chat participants: ${
+            errors.join("; ")
+          }`,
+        );
+      }
+      agents.push(selected);
+      speaker = selected;
+      result = selectedResult;
+    } else {
+      speaker = agents[index % agents.length];
+      const peer = agents[(index + 1) % agents.length];
+      result = await invoke(
+        speaker,
+        turnPrompt({
+          originalPrompt: prepared.prompt,
+          turns,
+          speaker,
+          peer,
+          round: index + 1,
+          totalRounds: rounds,
+        }),
+      );
+    }
+    if (
+      result.provider !== speaker.provider || result.model !== speaker.model
+    ) {
+      throw new Error(
+        `QuorumRouter blocked: agent identity changed during dialogue (expected=${speaker.provider}/${speaker.model} actual=${result.provider}/${result.model})`,
+      );
+    }
+    const content = summarize(redact(result.raw_content), 900);
+    const previous = turns.at(-1);
+    const turn: AgentChatTurn = {
+      round: index + 1,
+      provider: result.provider,
+      model: result.model,
+      reply_to: previous
+        ? {
+          provider: previous.provider,
+          model: previous.model,
+          round: previous.round,
+        }
+        : undefined,
+      content,
+    };
+    const alreadyAnnounced = announced;
+    turns.push(turn);
+    results.push({
+      ...result,
+      raw_content: content,
+      response_summary: content,
+    });
+    announce();
+    if (alreadyAnnounced) onProgress?.({ type: "turn", turn });
+  }
+
+  const trace = await buildTrace({
+    command: "agent-chat",
+    mode: "agent_chat",
+    authMode,
+    prompt: prepared.prompt,
+    promptContext: prepared.context,
+    results,
+    agentChat: true,
+    agentChatTurns: turns,
+    errors,
+    providerSelectionHonored: true,
+    fallbackUsed: agents.some((agent) => agent.source === "env_fallback"),
+  });
+  const tracePath = await writeTrace("agent-chat-trace", trace);
+  onProgress?.({ type: "complete", turnCount: turns.length });
+  return { tracePath, turns };
+}

package/templates/basic/src/auth.ts

@@ -0,0 +1,58 @@
+import { printLoginGuidance } from "./auth_oauth.ts";
+import { readRouterEnv } from "./env.ts";
+import {
+  discoverInventoryWithModelListing,
+  envFallbackConfigured,
+  invokableEntries,
+} from "./auth_session.ts";
+import { printInventoryTable } from "./model_inventory.ts";
+import { parseAuthMode } from "./schema.ts";
+
+export async function runAuthStatus(): Promise<void> {
+  const authMode = parseAuthMode(readRouterEnv("QUORUM_ROUTER_AUTH_MODE"));
+  const inventory = await discoverInventoryWithModelListing(authMode);
+  console.log("QuorumRouter auth status");
+  console.log(`Auth mode: ${authMode}`);
+  console.log("Preferred path: OAuth/session/local-wrapper first");
+  console.log("Provider request sent: false");
+  console.log("Credential values printed: false");
+  console.log(`Env fallback configured: ${envFallbackConfigured()}`);
+  printInventoryTable(inventory);
+  const usableEntries = invokableEntries(inventory);
+  if (usableEntries.length === 0) {
+    console.log("Status: missing usable OAuth/session/wrapper provider");
+    console.log("Next action: deno task auth:login");
+  } else if (authMode === "env") {
+    console.log("Status: explicit private env fallback is configured");
+    console.log(
+      'Next action: RUN_EXTERNAL_MODEL_DOGFOOD=1 deno task route:once --prompt "Review this README for risky claims."',
+    );
+  } else {
+    console.log(
+      "Status: at least one OAuth/session/wrapper provider appears usable",
+    );
+    console.log(
+      'Next action: RUN_EXTERNAL_MODEL_DOGFOOD=1 deno task route:once --prompt "Review this README for risky claims."',
+    );
+  }
+}
+
+export function runAuthLogin(): never {
+  return printLoginGuidance();
+}
+
+export async function runAuthLogout(): Promise<void> {
+  try {
+    await Deno.remove(".quorum-router", { recursive: true });
+  } catch (error) {
+    if (!(error instanceof Deno.errors.NotFound)) throw error;
+  }
+  console.log("QuorumRouter auth logout");
+  console.log(
+    "Removed generated local session metadata directory if present: .quorum-router/",
+  );
+  console.log(
+    "Provider CLI/browser sessions are managed by each provider CLI and were not modified.",
+  );
+  console.log("Credential values printed: false");
+}

package/templates/basic/src/auth_env_fallback.ts

@@ -0,0 +1,78 @@
+import { redact, summarize } from "./redact.ts";
+import type { ProviderResult } from "./schema.ts";
+import { readRouterEnv } from "./env.ts";
+
+function requiredEnv(name: string): string {
+  const value = Deno.env.get(name)?.trim();
+  if (!value) {
+    throw new Error(`QuorumRouter env fallback blocked: missing ${name}`);
+  }
+  return value;
+}
+
+export function chatCompletionsUrl(baseUrl: string): string {
+  let url: URL;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new Error(
+      "QuorumRouter env fallback blocked: QUORUM_ROUTER_PROVIDER_BASE_URL must be a valid URL",
+    );
+  }
+  const normalizedPath = url.pathname.replace(/\/+$/, "");
+  if (normalizedPath.endsWith("/chat/completions")) {
+    url.pathname = normalizedPath;
+    return url.toString();
+  }
+  url.pathname = `${normalizedPath}/chat/completions`;
+  return url.toString();
+}
+
+export async function callEnvFallback(prompt: string): Promise<ProviderResult> {
+  const baseUrl = requiredEnv("QUORUM_ROUTER_PROVIDER_BASE_URL");
+  const credential = requiredEnv("QUORUM_ROUTER_PROVIDER_API_KEY");
+  const model = requiredEnv("QUORUM_ROUTER_PROVIDER_MODEL");
+  const provider = readRouterEnv("QUORUM_ROUTER_PROVIDER_LABEL")?.trim() ||
+    "OpenAI-compatible env fallback";
+  const response = await fetch(chatCompletionsUrl(baseUrl), {
+    method: "POST",
+    signal: AbortSignal.timeout(120_000),
+    headers: {
+      authorization: `Bearer ${credential}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      model,
+      messages: [{ role: "user", content: prompt }],
+      temperature: 0,
+    }),
+  });
+  if (!response.ok) {
+    const body = redact(await response.text().catch(() => ""), [credential]);
+    throw new Error(
+      `QuorumRouter env fallback blocked: env fallback HTTP ${response.status}${
+        body ? `: ${body.slice(0, 300)}` : ""
+      }`,
+    );
+  }
+  const json = await response.json() as {
+    choices?: Array<{ message?: { content?: unknown }; text?: unknown }>;
+  };
+  const content = json.choices?.[0]?.message?.content ??
+    json.choices?.[0]?.text;
+  if (typeof content !== "string" || !content.trim()) {
+    throw new Error(
+      "QuorumRouter env fallback blocked: env fallback returned unexpected response shape",
+    );
+  }
+  return {
+    provider,
+    model,
+    model_id: `env/${model}`,
+    source: "env_fallback",
+    response_received: true,
+    schema_valid: true,
+    response_summary: summarize(content),
+    raw_content: content,
+  };
+}

package/templates/basic/src/auth_oauth.ts

@@ -0,0 +1,19 @@
+export function browserLoginSupported(): boolean {
+  return false;
+}
+
+export function printLoginGuidance(): never {
+  console.error(
+    "OAuth/session login is not configured for this generated scaffold yet.",
+  );
+  console.error("Use an installed provider CLI login, then rerun:");
+  console.error("  deno task intake");
+  console.error("");
+  console.error(
+    "Generic env fallback exists, but it is private/manual and not the preferred path.",
+  );
+  console.error(
+    "Never paste tokens into chat/logs and never commit .env or .quorum-router/.",
+  );
+  Deno.exit(1);
+}

package/templates/basic/src/auth_session.ts

@@ -0,0 +1,271 @@
+import {
+  envFallbackEntry,
+  LOCAL_PROVIDER_SPECS,
+  providerSelectionMatches,
+  type ProviderSelectionRequest,
+  type ProviderSpec,
+} from "./provider_registry.ts";
+import { redact, summarize } from "./redact.ts";
+import { readRouterEnv } from "./env.ts";
+import {
+  type AuthMode,
+  type ModelInventory,
+  type ModelInventoryEntry,
+  parseAuthMode,
+} from "./schema.ts";
+
+export function commandExists(command: string): boolean {
+  const path = Deno.env.get("PATH") ?? "";
+  const sep = Deno.build.os === "windows" ? ";" : ":";
+  const exts = Deno.build.os === "windows"
+    ? (Deno.env.get("PATHEXT") ?? ".EXE;.CMD;.BAT").split(";")
+    : [""];
+  for (const dir of path.split(sep)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      try {
+        const stat = Deno.statSync(`${dir}/${command}${ext}`);
+        if (!stat.isFile) continue;
+        if (Deno.build.os === "windows" || ((stat.mode ?? 0) & 0o111) !== 0) {
+          return true;
+        }
+      } catch { /* keep scanning */ }
+    }
+  }
+  return false;
+}
+
+export function envFallbackConfigured(): boolean {
+  return Boolean(
+    readRouterEnv("QUORUM_ROUTER_PROVIDER_BASE_URL")?.trim() &&
+      readRouterEnv("QUORUM_ROUTER_PROVIDER_API_KEY")?.trim() &&
+      readRouterEnv("QUORUM_ROUTER_PROVIDER_MODEL")?.trim(),
+  );
+}
+
+function includeForMode(entryAuth: string, mode: AuthMode): boolean {
+  if (mode === "auto") return entryAuth !== "env";
+  if (mode === "wrapper") {
+    return entryAuth === "oauth" || entryAuth === "session";
+  }
+  if (mode === "oauth") return entryAuth === "oauth";
+  if (mode === "session") return entryAuth === "session";
+  return entryAuth === "env";
+}
+
+function specKey(spec: ProviderSpec): string {
+  return `${spec.provider}\u0000${spec.model_id}`;
+}
+
+function specForEntry(entry: ModelInventoryEntry): ProviderSpec | undefined {
+  return LOCAL_PROVIDER_SPECS.find((spec) =>
+    specKey(spec) === `${entry.provider}\u0000${entry.model_id}`
+  );
+}
+
+export function discoverInventory(
+  mode = parseAuthMode(readRouterEnv("QUORUM_ROUTER_AUTH_MODE")),
+): ModelInventory {
+  const entries: ModelInventoryEntry[] = [];
+  for (const spec of LOCAL_PROVIDER_SPECS) {
+    if (!includeForMode(spec.auth_mode, mode)) continue;
+    const exists = spec.command ? commandExists(spec.command) : false;
+    entries.push({
+      provider: spec.provider,
+      auth_mode: spec.auth_mode,
+      model: spec.model,
+      model_id: spec.model_id,
+      source: spec.source,
+      available: exists,
+      blocked_reason: exists
+        ? undefined
+        : `missing local command: ${spec.command}`,
+      can_list_models: false,
+      list_blocked_reason: spec.list_blocked_reason ??
+        (spec.list_models_args
+          ? "model listing not run in sync inventory path"
+          : "no safe non-interactive model list command configured"),
+      can_invoke: exists,
+      command: spec.command,
+      args_template: spec.args_template,
+      notes: exists
+        ? [
+          ...spec.notes,
+          "Command exists; actual auth is verified only during explicit opt-in invocation.",
+        ]
+        : spec.notes,
+    });
+  }
+
+  const fallback = envFallbackEntry(envFallbackConfigured());
+  if (mode === "env") {
+    entries.push(fallback);
+  } else if (mode === "auto") {
+    // Report but do not silently use env fallback in auto mode.
+    entries.push({
+      ...fallback,
+      available: false,
+      can_invoke: false,
+      blocked_reason: fallback.available
+        ? "env fallback configured but not used unless QUORUM_ROUTER_AUTH_MODE=env"
+        : fallback.blocked_reason,
+    });
+  }
+
+  return {
+    generated_at: new Date().toISOString(),
+    auth_mode: mode,
+    entries,
+    available_count: entries.filter((entry) => entry.available).length,
+    blocked_count: entries.filter((entry) => !entry.available).length,
+    env_fallback_configured: envFallbackConfigured(),
+    env_fallback_used: mode === "env" && envFallbackConfigured(),
+  };
+}
+
+function listCommandEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (
+    const name of [
+      "PATH",
+      "HOME",
+      "TMPDIR",
+      "TMP",
+      "TEMP",
+      "LANG",
+      "LC_ALL",
+      "TERM",
+    ]
+  ) {
+    const value = Deno.env.get(name);
+    if (value) env[name] = value;
+  }
+  return env;
+}
+
+async function outputWithTimeout(
+  command: string,
+  args: string[],
+  timeoutMs: number,
+): Promise<Deno.CommandOutput> {
+  const child = new Deno.Command(command, {
+    args,
+    clearEnv: true,
+    env: listCommandEnv(),
+    stdin: "null",
+    stdout: "piped",
+    stderr: "piped",
+  }).spawn();
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  let killId: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      child.output(),
+      new Promise<Deno.CommandOutput>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          try {
+            child.kill("SIGTERM");
+          } catch { /* best effort */ }
+          killId = setTimeout(() => {
+            try {
+              child.kill("SIGKILL");
+            } catch { /* best effort */ }
+            reject(new Error("model listing timed out"));
+          }, 1_000);
+        }, timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+    if (killId) clearTimeout(killId);
+  }
+}
+
+export function parseGrokModelList(output: string): string[] {
+  const models = new Set<string>();
+  for (const rawLine of output.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const match = line.match(/^(?:[*-])\s+([^\s(]+)(?:\s+\(default\))?$/);
+    if (match) models.add(match[1]);
+  }
+  return [...models].sort();
+}
+
+async function enrichModelListing(
+  entry: ModelInventoryEntry,
+): Promise<ModelInventoryEntry> {
+  const spec = specForEntry(entry);
+  if (!entry.available || !entry.command || !spec?.list_models_args) {
+    return entry;
+  }
+  try {
+    const output = await outputWithTimeout(
+      entry.command,
+      spec.list_models_args,
+      10_000,
+    );
+    const stdout = new TextDecoder().decode(output.stdout);
+    const stderr = new TextDecoder().decode(output.stderr);
+    if (output.code !== 0) {
+      return {
+        ...entry,
+        can_list_models: false,
+        list_blocked_reason: summarize(redact(stderr || stdout), 300),
+      };
+    }
+    const listedModels = entry.provider === "xAI"
+      ? parseGrokModelList(stdout)
+      : [];
+    return {
+      ...entry,
+      can_list_models: listedModels.length > 0,
+      listed_models: listedModels,
+      list_blocked_reason: listedModels.length > 0
+        ? undefined
+        : "model list command succeeded but no model ids were parsed",
+      notes: listedModels.length > 0
+        ? [
+          ...entry.notes,
+          `Listed ${listedModels.length} model(s) via safe list-only command.`,
+        ]
+        : entry.notes,
+    };
+  } catch (error) {
+    return {
+      ...entry,
+      can_list_models: false,
+      list_blocked_reason: summarize(
+        redact(error instanceof Error ? error.message : String(error)),
+        300,
+      ),
+    };
+  }
+}
+
+export async function discoverInventoryWithModelListing(
+  mode = parseAuthMode(readRouterEnv("QUORUM_ROUTER_AUTH_MODE")),
+  request: ProviderSelectionRequest = {},
+): Promise<ModelInventory> {
+  const inventory = discoverInventory(mode);
+  const entries = await Promise.all(inventory.entries.map((entry) => {
+    if (
+      request.providerLabel &&
+      !providerSelectionMatches(entry, request.providerLabel)
+    ) {
+      return Promise.resolve(entry);
+    }
+    return enrichModelListing(entry);
+  }));
+  return {
+    ...inventory,
+    entries,
+  };
+}
+
+export function invokableEntries(
+  inventory: ModelInventory,
+): ModelInventoryEntry[] {
+  return inventory.entries.filter((entry) =>
+    entry.available && entry.can_invoke
+  );
+}