@saadnvd1/agent-os 0.3.471 → 0.3.472

package/lib/models/providers.ts

@@ -0,0 +1,163 @@
+/**
+ * Where a model runs. A provider is config: Anthropic through the Claude
+ * login (no key), or an Anthropic- or OpenAI-compatible endpoint with a base
+ * URL, a reference to its key and its model names. The key itself is never
+ * here: only where to fetch it from at launch (lib/models/secrets).
+ * Imported by the browser too, so no Node modules here.
+ */
+
+import { ANTHROPIC } from "./roles";
+
+// Where a provider's key lives. Never the key.
+export type SecretRef =
+  | { kind: "tokenvault"; project: string; desc?: string }
+  | { kind: "keychain"; service: string; account?: string }
+  | { kind: "env"; name: string };
+
+export type ProviderApi = "anthropic" | "openai";
+
+export interface ModelTiers {
+  opus?: string;
+  sonnet?: string;
+  haiku?: string;
+}
+
+export interface ModelProvider {
+  id: string;
+  label: string;
+  api: ProviderApi;
+  // Absent for Anthropic itself, which uses the Claude login.
+  baseUrl?: string;
+  auth?: SecretRef;
+  // How the key is sent: Authorization: Bearer, or x-api-key.
+  authHeader?: "bearer" | "x-api-key";
+  models: string[];
+  // Claude Code's tiers mapped to this provider's models, so subagents and
+  // background work (which ask for "haiku" or "sonnet") route here too.
+  tiers?: ModelTiers;
+  // Plain settings the endpoint wants (a longer timeout, say). Never a key.
+  env?: Record<string, string>;
+  enabled: boolean;
+}
+
+export interface ModelPrice {
+  input: number;
+  cacheWrite: number;
+  cacheRead: number;
+  output: number;
+}
+
+export const ANTHROPIC_PROVIDER: ModelProvider = {
+  id: ANTHROPIC,
+  label: "Anthropic (Claude login)",
+  api: "anthropic",
+  models: [
+    "claude-opus-5-5",
+    "claude-sonnet-5-5",
+    "claude-haiku-4-5-20251001",
+    "claude-fable-5-1",
+  ],
+  enabled: true,
+};
+
+// Checked against each provider's docs on 2026-10-11: DeepSeek
+// (api-docs.deepseek.com/guides/anthropic_api) and Z.ai
+// (docs.z.ai/devpack/tool/claude). Off until a key reference is set.
+export const PROVIDER_PRESETS: ModelProvider[] = [
+  ANTHROPIC_PROVIDER,
+  {
+    id: "deepseek",
+    label: "DeepSeek",
+    api: "anthropic",
+    baseUrl: "https://api.deepseek.com/anthropic",
+    authHeader: "x-api-key",
+    models: ["deepseek-v4-pro", "deepseek-flash"],
+    tiers: {
+      opus: "deepseek-v4-pro",
+      sonnet: "deepseek-flash",
+      haiku: "deepseek-flash",
+    },
+    enabled: false,
+  },
+  {
+    id: "zai",
+    label: "Z.ai (GLM)",
+    api: "anthropic",
+    baseUrl: "https://api.z.ai/api/anthropic",
+    authHeader: "bearer",
+    models: ["glm-5.3", "glm-5.3-flash"],
+    tiers: { opus: "glm-5.3", sonnet: "glm-5.3", haiku: "glm-5.3-flash" },
+    env: { API_TIMEOUT_MS: "3000000" },
+    enabled: false,
+  },
+];
+
+// Dollars per million tokens, from each provider's price page on
+// 2026-10-11. DeepSeek and GLM have no cache-write price (a write costs
+// what input does), and DeepSeek's are its peak prices.
+export const DEFAULT_PRICES: Record<string, ModelPrice> = {
+  "anthropic/claude-opus-5-5": {
+    input: 4,
+    cacheWrite: 5,
+    cacheRead: 0.2,
+    output: 20,
+  },
+  "anthropic/claude-sonnet-5-5": {
+    input: 2,
+    cacheWrite: 2.5,
+    cacheRead: 0.1,
+    output: 10,
+  },
+  "anthropic/claude-haiku-4-5-20251001": {
+    input: 1,
+    cacheWrite: 1.25,
+    cacheRead: 0.1,
+    output: 5,
+  },
+  "anthropic/claude-fable-5-1": {
+    input: 10,
+    cacheWrite: 12.5,
+    cacheRead: 0.25,
+    output: 50,
+  },
+  "deepseek/deepseek-v4-pro": {
+    input: 1.32,
+    cacheWrite: 1.32,
+    cacheRead: 0.044,
+    output: 3.96,
+  },
+  "deepseek/deepseek-flash": {
+    input: 0.3,
+    cacheWrite: 0.3,
+    cacheRead: 0.006,
+    output: 1.2,
+  },
+  "zai/glm-5.3": { input: 1.4, cacheWrite: 1.4, cacheRead: 0.26, output: 4.4 },
+  "zai/glm-5.3-flash": {
+    input: 0.15,
+    cacheWrite: 0.15,
+    cacheRead: 0.03,
+    output: 0.5,
+  },
+};
+
+// Claude Code's family aliases, priced as the model each stands for.
+export const ANTHROPIC_ALIASES: Record<string, string> = {
+  opus: "claude-opus-5-5",
+  sonnet: "claude-sonnet-5-5",
+  haiku: "claude-haiku-4-5-20251001",
+  fable: "claude-fable-5-1",
+};
+
+// Anthropic is billed by the plan, not per token: a turn there costs a share
+// of the plan's window, and its dollars are what the API would have charged.
+export const isMetered = (providerId: string) => providerId !== ANTHROPIC;
+
+export function describeSecretRef(ref: SecretRef | undefined): string {
+  if (!ref) return "no key";
+  if (ref.kind === "tokenvault")
+    return `tokenvault ${ref.project}${ref.desc ? ` "${ref.desc}"` : ""}`;
+  if (ref.kind === "keychain")
+    return `Keychain ${ref.service}${ref.account ? ` (${ref.account})` : ""}`;
+  return `$${ref.name}`;
+}

package/lib/models/resolve.ts

@@ -0,0 +1,246 @@
+/**
+ * Which model a piece of work runs on, and what its agent needs to reach
+ * it. The most specific setting wins: the task's own override, then its
+ * workspace's, then Settings, then AGENTOS_REVIEW_MODEL or
+ * AGENTOS_TITLE_MODEL, then the default (lib/models/roles).
+ */
+
+import { db, type Session } from "../db";
+import { getProject } from "../projects";
+import {
+  effectiveModels,
+  roleMapSchema,
+  savedModelSettings,
+  workspaceModels,
+  type EffectiveModels,
+  type RoleMap,
+} from "./config";
+import { ANTHROPIC_PROVIDER, type ModelProvider } from "./providers";
+import {
+  ANTHROPIC,
+  DEFAULT_ROLE_MODELS,
+  GATE_ROLES,
+  formatModelRef,
+  isModelRole,
+  parseModelRef,
+  sessionRole,
+  type ModelRole,
+} from "./roles";
+import {
+  resolveSecret,
+  secretShellExpansion,
+  type SecretCommand,
+} from "./secrets";
+
+export type RoleSource = "task" | "workspace" | "settings" | "env" | "default";
+
+// The server's own environment can still stand in for a role's default:
+// what AgentOS read before model routing existed.
+const ENV_ROLE_MODELS: Partial<Record<ModelRole, string>> = {
+  review: "AGENTOS_REVIEW_MODEL",
+  scope: "AGENTOS_REVIEW_MODEL",
+  helper: "AGENTOS_TITLE_MODEL",
+};
+
+const envModel = (role: ModelRole): string | undefined => {
+  const name = ENV_ROLE_MODELS[role];
+  return (name && process.env[name]?.trim()) || undefined;
+};
+
+export interface RoutedModel {
+  role: ModelRole;
+  ref: string;
+  provider: ModelProvider;
+  model: string;
+  source: RoleSource;
+}
+
+// A task's override: one model for all its roles, or a model per role.
+export type ModelOverride = string | RoleMap;
+
+export function parseOverride(value: unknown): ModelOverride | null {
+  if (value == null || value === "") return null;
+  if (typeof value === "string") {
+    const ref = value.trim();
+    providerFor(parseModelRef(ref).provider);
+    return ref.includes("/") ? ref : formatModelRef(parseModelRef(ref));
+  }
+  const got = roleMapSchema.safeParse(value);
+  const gate = got.success && GATE_ROLES.find((r) => got.data[r]);
+  if (gate)
+    throw new Error(
+      `model: a task can't pick its own ${gate} model; set it in Settings or the workspace`
+    );
+  if (!got.success)
+    throw new Error(
+      `model: give "provider/model", or a map of role to "provider/model"`
+    );
+  for (const ref of Object.values(got.data))
+    if (ref) providerFor(parseModelRef(ref).provider);
+  return Object.keys(got.data).length ? got.data : null;
+}
+
+const overrideFor = (o: ModelOverride | null | undefined, role: ModelRole) =>
+  GATE_ROLES.includes(role) ? undefined : typeof o === "string" ? o : o?.[role];
+
+// The provider by id, or throws why it can't be used.
+export function providerFor(
+  id: string,
+  models: EffectiveModels = effectiveModels()
+): ModelProvider {
+  if (id === ANTHROPIC) return ANTHROPIC_PROVIDER;
+  const p = models.providers.find((x) => x.id === id);
+  if (!p) throw new Error(`No model provider "${id}" (Settings > Models)`);
+  if (!p.enabled) throw new Error(`The ${p.label} provider is turned off`);
+  if (!p.baseUrl || !p.auth)
+    throw new Error(`The ${p.label} provider needs a base URL and a key`);
+  if (p.api !== "anthropic")
+    throw new Error(
+      `${p.label} speaks the OpenAI API; Claude Code needs an Anthropic-compatible endpoint`
+    );
+  return p;
+}
+
+export function resolveRole(
+  role: ModelRole,
+  opts: { workspaceId?: string | null; override?: ModelOverride | null } = {},
+  models: EffectiveModels = effectiveModels()
+): RoutedModel {
+  const task = overrideFor(opts.override, role);
+  const ws = opts.workspaceId
+    ? workspaceModels(opts.workspaceId).roles?.[role]
+    : undefined;
+  const saved = models.roles[role];
+  // The variable stands in only where Settings names nothing for the role.
+  const env =
+    saved === DEFAULT_ROLE_MODELS[role] && !savedModelSettings().roles?.[role]
+      ? envModel(role)
+      : undefined;
+  const [ref, source]: [string, RoleSource] = task
+    ? [task, "task"]
+    : ws
+      ? [ws, "workspace"]
+      : saved !== DEFAULT_ROLE_MODELS[role]
+        ? [saved, "settings"]
+        : env
+          ? [env, "env"]
+          : [saved, "default"];
+  const parsed = parseModelRef(ref);
+  return {
+    role,
+    ref: formatModelRef(parsed),
+    provider: providerFor(parsed.provider, models),
+    model: parsed.model,
+    source,
+  };
+}
+
+// The role's built-in model on the Claude login: what work falls back to
+// when the provider it's routed to can't be used.
+export function defaultRoute(role: ModelRole): RoutedModel {
+  const parsed = parseModelRef(DEFAULT_ROLE_MODELS[role]);
+  return {
+    role,
+    ref: formatModelRef(parsed),
+    provider: ANTHROPIC_PROVIDER,
+    model: parsed.model,
+    source: "default",
+  };
+}
+
+export function resolveRoleOrDefault(
+  role: ModelRole,
+  opts: { workspaceId?: string | null } = {}
+): RoutedModel {
+  try {
+    return resolveRole(role, opts);
+  } catch {
+    return defaultRoute(role);
+  }
+}
+
+// A session's workspace: an orchestrator's own, or its project's.
+export function sessionWorkspace(
+  session: Pick<Session, "workspace_id" | "project_id">
+): string | null {
+  if (session.workspace_id) return session.workspace_id;
+  return session.project_id
+    ? (getProject(session.project_id)?.workspace_id ?? null)
+    : null;
+}
+
+export function taskOverride(
+  session: Pick<Session, "model_overrides">
+): ModelOverride | null {
+  if (!session.model_overrides) return null;
+  try {
+    return parseOverride(JSON.parse(session.model_overrides));
+  } catch {
+    return null;
+  }
+}
+
+// What the agent's environment needs beyond the model name, with the key
+// fetched now. Nothing for Anthropic: the Claude login is the default.
+export async function providerEnv(
+  provider: ModelProvider,
+  model: string,
+  exec?: SecretCommand
+): Promise<Record<string, string>> {
+  if (provider.id === ANTHROPIC) return {};
+  const key = await resolveSecret(provider.auth!, exec);
+  return { ...routingEnv(provider, model), [authVar(provider)]: key };
+}
+
+// The same for a terminal launch: the plain settings, and shell text that
+// sets the key from its reference inside the agent's shell.
+export function providerShellEnv(
+  provider: ModelProvider,
+  model: string
+): { env: Record<string, string>; exportKey: string } {
+  if (provider.id === ANTHROPIC) return { env: {}, exportKey: "" };
+  return {
+    env: routingEnv(provider, model),
+    exportKey: `export ${authVar(provider)}=${secretShellExpansion(provider.auth!)};`,
+  };
+}
+
+const authVar = (p: ModelProvider) =>
+  p.authHeader === "x-api-key" ? "ANTHROPIC_API_KEY" : "ANTHROPIC_AUTH_TOKEN";
+
+// The endpoint, Claude Code's tiers mapped to its models (so subagents and
+// background calls asking for "haiku" stay on it), and the other key
+// variable emptied so a key in AgentOS's own environment isn't sent there.
+function routingEnv(p: ModelProvider, model: string): Record<string, string> {
+  const other =
+    authVar(p) === "ANTHROPIC_API_KEY"
+      ? "ANTHROPIC_AUTH_TOKEN"
+      : "ANTHROPIC_API_KEY";
+  return {
+    ...p.env,
+    ANTHROPIC_BASE_URL: p.baseUrl!,
+    [other]: "",
+    ANTHROPIC_DEFAULT_OPUS_MODEL: p.tiers?.opus ?? model,
+    ANTHROPIC_DEFAULT_SONNET_MODEL: p.tiers?.sonnet ?? model,
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: p.tiers?.haiku ?? model,
+    CLAUDE_CODE_SUBAGENT_MODEL: p.tiers?.sonnet ?? model,
+  };
+}
+
+// Records what a session runs on: the model its CLI is given, and its
+// provider (NULL for Anthropic).
+export function setSessionModel(sessionId: string, routed: RoutedModel): void {
+  db.prepare(
+    `UPDATE sessions SET model = ?, model_provider = ? WHERE id = ?`
+  ).run(
+    routed.model,
+    routed.provider.id === ANTHROPIC ? null : routed.provider.id,
+    sessionId
+  );
+}
+
+export const sessionModelRef = (
+  s: Pick<Session, "model" | "model_provider">
+): string => `${s.model_provider ?? ANTHROPIC}/${s.model}`;
+
+export { isModelRole, sessionRole };

package/lib/models/resume.ts

@@ -0,0 +1,99 @@
+/**
+ * Resuming a task on another model: its conversation and worktree carry on,
+ * only the model (and maybe the provider) under it changes. The choice is
+ * kept as the task's own override, so later turns and restarts stay on it.
+ */
+
+import { db, type Session } from "../db";
+import { chatState, sendChat } from "../chat/runner";
+import { launchPending } from "../tasks/launch-gate";
+import { killTmux } from "../tasks/start";
+import { launchClaude } from "../agents/launch";
+import { switchSessionModel } from "./session-model";
+import {
+  parseOverride,
+  resolveRole,
+  sessionWorkspace,
+  setSessionModel,
+  taskOverride,
+  type ModelOverride,
+} from "./resolve";
+import { sessionRole } from "./roles";
+
+export const RESUME_MESSAGE =
+  "You were paused. Carry on where you left off: check the worktree and the conversation above for where things stand, then finish the task.";
+
+// A per-role map adds to the one it has; one model replaces it.
+export function mergeOverride(
+  before: ModelOverride | null,
+  next: ModelOverride
+): ModelOverride {
+  if (typeof next === "string" || !before) return next;
+  if (typeof before === "string") return next;
+  return { ...before, ...next };
+}
+
+export interface ResumeResult {
+  ref: string;
+  // Whether a message went to its agent now: a task still setting up, or
+  // held, starts on the new model by itself.
+  resumed: boolean;
+}
+
+export async function resumeOnModel(
+  sessionId: string,
+  model: unknown,
+  message = RESUME_MESSAGE
+): Promise<ResumeResult> {
+  const s = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(sessionId) as
+    | Session
+    | undefined;
+  if (!s?.task_status) throw new Error("No such task");
+  if (s.task_status !== "running")
+    throw new Error(
+      `That task is ${s.task_status}; only a running one resumes`
+    );
+  const next = parseOverride(model);
+  if (!next) throw new Error("Pick a model");
+  const override = mergeOverride(taskOverride(s), next);
+  const routed = resolveRole(sessionRole(s), {
+    workspaceId: sessionWorkspace(s),
+    override,
+  });
+  const state = s.view === "chat" ? chatState(sessionId) : null;
+  if (state === "running" || state === "waiting")
+    throw new Error(
+      "It's mid-turn: stop it first, or wait for the turn to end"
+    );
+  db.prepare(`UPDATE sessions SET model_overrides = ? WHERE id = ?`).run(
+    JSON.stringify(override),
+    sessionId
+  );
+  if (launchPending(sessionId)) {
+    setSessionModel(sessionId, routed);
+    return { ref: routed.ref, resumed: false };
+  }
+  if (s.view === "chat") {
+    await switchSessionModel(sessionId, routed);
+    await sendChat(sessionId, {
+      text: message,
+      origin: { kind: "decision", label: `Resumed on ${routed.ref}` },
+    });
+    return { ref: routed.ref, resumed: true };
+  }
+  if (!s.claude_session_id || !s.worktree_path)
+    throw new Error("Its terminal conversation can't be resumed");
+  setSessionModel(sessionId, routed);
+  await killTmux(s.tmux_name);
+  await launchClaude({
+    sessionId,
+    tmuxName: s.tmux_name,
+    cwd: s.worktree_path,
+    model: routed.model,
+    provider: routed.provider.id === "anthropic" ? null : routed.provider.id,
+    prompt: message,
+    brief: s.task_brief ?? undefined,
+    resume: s.claude_session_id,
+  });
+  return { ref: routed.ref, resumed: true };
+}

package/lib/models/roles.ts

@@ -0,0 +1,98 @@
+/**
+ * The kinds of work AgentOS launches agents for, and the model each runs on
+ * unless Settings, a workspace or the task says otherwise. A model is named
+ * by a reference, "provider/model": the provider is one of lib/models/
+ * providers, and the model is that provider's own id. Imported by the
+ * browser too, so no Node modules here.
+ */
+
+export const MODEL_ROLES = [
+  "plan",
+  "implement",
+  "orchestrator",
+  "review",
+  "scope",
+  "interactive",
+  "helper",
+] as const;
+
+export type ModelRole = (typeof MODEL_ROLES)[number];
+
+export const ROLE_LABELS: Record<ModelRole, { label: string; hint: string }> = {
+  plan: {
+    label: "Task planning",
+    hint: "A task's plan step, written to a file before any code changes",
+  },
+  implement: {
+    label: "Task implementation",
+    hint: "A task's agent, following the plan in its worktree",
+  },
+  orchestrator: { label: "Orchestrator", hint: "A workspace's orchestrator" },
+  review: {
+    label: "Gate review",
+    hint: "The independent review a PR passes before it merges",
+  },
+  scope: { label: "Scope check", hint: "Whether a diff stays in its card" },
+  interactive: {
+    label: "Interactive sessions",
+    hint: "Sessions you start and talk to yourself",
+  },
+  helper: {
+    label: "Chat & summary helpers",
+    hint: "Titles, summaries and digests",
+  },
+};
+
+export const ANTHROPIC = "anthropic";
+const OPUS = `${ANTHROPIC}/claude-opus-5-5`;
+const SONNET = `${ANTHROPIC}/claude-sonnet-5-5`;
+const HAIKU = `${ANTHROPIC}/claude-haiku-4-5-20251001`;
+
+// Claude stays the default for every role: another provider is opt-in.
+export const DEFAULT_ROLE_MODELS: Record<ModelRole, string> = {
+  plan: OPUS,
+  review: OPUS,
+  implement: SONNET,
+  orchestrator: SONNET,
+  scope: SONNET,
+  interactive: OPUS,
+  helper: HAIKU,
+};
+
+// The roles that gate a task's merge: only Settings and its workspace pick
+// their model, never the task (or the orchestrator that started it), so
+// work can't choose its own reviewer.
+export const GATE_ROLES: readonly ModelRole[] = ["review", "scope"];
+export const TASK_ROLES = MODEL_ROLES.filter((r) => !GATE_ROLES.includes(r));
+
+export const isModelRole = (v: unknown): v is ModelRole =>
+  typeof v === "string" && (MODEL_ROLES as readonly string[]).includes(v);
+
+export interface ModelRef {
+  provider: string;
+  model: string;
+}
+
+// "provider/model", split at the first slash (a model id may hold more).
+// A bare model ("opus", "claude-sonnet-5-5") is Anthropic's.
+export function parseModelRef(ref: string): ModelRef {
+  const s = ref.trim();
+  const at = s.indexOf("/");
+  if (at <= 0) return { provider: ANTHROPIC, model: s };
+  return { provider: s.slice(0, at), model: s.slice(at + 1) };
+}
+
+export const formatModelRef = (r: ModelRef) => `${r.provider}/${r.model}`;
+
+export const REF_PATTERN = /^[a-z0-9][a-z0-9_-]*\/[\w.:@/-]+$/i;
+
+// The role a session's next turn runs as.
+export function sessionRole(session: {
+  role?: string | null;
+  task_status?: string | null;
+  plan_phase?: string | null;
+}): ModelRole {
+  if (session.role === "orchestrator") return "orchestrator";
+  if (!session.task_status) return "interactive";
+  return session.plan_phase === "planning" ? "plan" : "implement";
+}

package/lib/models/secrets.ts

@@ -0,0 +1,86 @@
+/**
+ * A provider's key, fetched from where its reference points at the moment
+ * an agent launches, and handed straight to that agent's environment. It is
+ * never written anywhere: not the database, not a log, not a prompt. Every
+ * key fetched is remembered in memory only so redact() can scrub it from
+ * any text on its way to a log or an error.
+ */
+
+import { execFile } from "child_process";
+import { shellQuote } from "../hosts/ssh";
+import type { SecretRef } from "./providers";
+
+export type SecretCommand = (cmd: string, args: string[]) => Promise<string>;
+
+const run: SecretCommand = (cmd, args) =>
+  new Promise((resolve, reject) =>
+    execFile(cmd, args, { timeout: 15_000 }, (err, stdout) =>
+      // Its stderr isn't passed on: a tool may echo what it was asked.
+      err ? reject(new Error(`${cmd} failed`)) : resolve(stdout)
+    )
+  );
+
+// An environment variable a key may be read from: one named for an API key,
+// never AgentOS's own nor its Claude login's, so a reference can't lift an
+// unrelated secret out of the server's environment.
+export const KEY_ENV_NAME =
+  /^(?!(?:ANTHROPIC|CLAUDE|AGENTOS)_)[A-Z][A-Z0-9_]*_API_KEY$/;
+
+// The command that prints the key, as argv; null for an environment
+// variable, which is read directly.
+export function secretCommand(ref: SecretRef): string[] | null {
+  if (ref.kind === "tokenvault")
+    return ["tv", "get", ref.project, ...(ref.desc ? [ref.desc] : [])];
+  if (ref.kind === "keychain")
+    return [
+      "security",
+      "find-generic-password",
+      "-s",
+      ref.service,
+      ...(ref.account ? ["-a", ref.account] : []),
+      "-w",
+    ];
+  return null;
+}
+
+// The same, as shell text that expands to the key inside the agent's own
+// shell (a terminal launch), so AgentOS never holds it at all.
+export function secretShellExpansion(ref: SecretRef): string {
+  const argv = secretCommand(ref);
+  if (!argv) return `"\${${ref.kind === "env" ? envName(ref.name) : ""}}"`;
+  return `"$(${argv.map(shellQuote).join(" ")})"`;
+}
+
+function envName(name: string): string {
+  if (!KEY_ENV_NAME.test(name))
+    throw new Error(
+      `A key can't be read from ${name}: name a *_API_KEY variable`
+    );
+  return name;
+}
+
+const seen = new Set<string>();
+
+export async function resolveSecret(
+  ref: SecretRef,
+  exec: SecretCommand = run
+): Promise<string> {
+  const argv = secretCommand(ref);
+  let value: string | undefined;
+  if (argv) {
+    const out = await exec(argv[0], argv.slice(1)).catch(() => {
+      throw new Error(`Couldn't read the key (${argv[0]} failed)`);
+    });
+    value = out.trim();
+  } else if (ref.kind === "env") value = process.env[envName(ref.name)]?.trim();
+  if (!value) throw new Error("The key reference resolved to nothing");
+  if (value.length >= 8) seen.add(value);
+  return value;
+}
+
+// Scrubs every key fetched so far out of the text.
+export function redact(text: string): string {
+  let out = text;
+  for (const s of seen) out = out.split(s).join("[redacted]");
+  return out;
+}