@agentswf/engine 0.0.0-stage → 0.1.0-beta.0

package/src/accounting/summary.ts

@@ -0,0 +1,385 @@
+import type {
+  AccountingFigures,
+  AttemptAccounting,
+  DecisionFigures,
+  ModelFigures,
+  RunAccounting,
+  SettledDecision,
+  SettledOperation,
+  TokenUsage,
+} from "@agentswf/contract/records";
+import { costOf, type PriceTable } from "./prices";
+import { addTokens } from "./tokens";
+
+const NONE: TokenUsage = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
+
+/** What ran between a run's stages, as a row of `byStage`. */
+export const NO_STAGE = "(no stage)";
+
+/**
+ * What a run cost and how long it took, from its usage and decision records alone, so a finished
+ * run can be priced again with another table. `entered` are the workflow stages entered, in order:
+ * each is a row timed by its own span, a reused one at zero; without them, a row per call path and
+ * key prefix, timed by what ran in it.
+ */
+export function summarizeRun(
+  usage: readonly SettledOperation[],
+  prices: PriceTable,
+  times: { startedAt: string; finishedAt: string },
+  decisions: readonly SettledDecision[],
+  entered: readonly { stage: string; spanMs: number }[] = [],
+): RunAccounting {
+  const spends = usage.flatMap((record) => record.spend ?? []);
+  const agentModels = unique(spends.map((spend) => spend.model));
+  const decisionModels = unique(decisions.filter((record) => record.tokens).map(decisionModelOf));
+  const models = unique([...agentModels, ...decisionModels]).sort();
+  const agentIds = unique(usage.map(agentOf));
+  const staged =
+    entered.length > 0 ||
+    usage.some((record) => record.stage !== undefined) ||
+    decisions.some((record) => record.stage !== undefined);
+  const stageOf = staged ? workflowStageOf : prefixStageOf;
+  const decisionStageOf = staged ? workflowStageOf : decisionPrefixStageOf;
+  const stages = unique([
+    ...entered.map(({ stage }) => stage),
+    ...usage.map(stageOf),
+    ...decisions.map(decisionStageOf),
+  ]).sort(noStageLast);
+  const billings = unique(usage.map((record) => record.billing)).filter(
+    (billing) => billing !== "unknown",
+  );
+  const figures = (
+    records: readonly SettledOperation[],
+    asked: readonly SettledDecision[] = [],
+  ): AccountingFigures => {
+    const agents = figuresOf(records, prices);
+    return asked.length === 0 ? agents : { ...agents, decisions: decisionFigures(asked, prices) };
+  };
+
+  return {
+    basis: prices.basis,
+    startedAt: times.startedAt,
+    finishedAt: times.finishedAt,
+    wallMs: Date.parse(times.finishedAt) - Date.parse(times.startedAt),
+    grouping: staged ? "stages" : "prefix",
+    billing: billings.length === 0 ? "unknown" : billings.length === 1 ? billings[0]! : "mixed",
+    totals: figures(usage, decisions),
+    byStage: stages.map((stage) => {
+      const records = usage.filter((record) => stageOf(record) === stage);
+      const asked = decisions.filter((record) => decisionStageOf(record) === stage);
+      const spanMs = entered.find((one) => one.stage === stage)?.spanMs ?? spanOf(records, asked);
+      return { stage, ...figures(records, asked), spanMs };
+    }),
+    byModel: models.map((model) => {
+      const agents = modelFigures(model, usage, prices);
+      const answered = decisions.filter(
+        (record) => record.tokens && decisionModelOf(record) === model,
+      );
+      return answered.length === 0 ? agents : withDecisions(agents, answered, prices);
+    }),
+    byAgent: agentIds.map((id) => {
+      const records = usage.filter((record) => agentOf(record) === id);
+      const first = records[0]!;
+      return {
+        callPath: first.callPath,
+        agent: first.agent,
+        execution: first.execution,
+        billing: first.billing,
+        ...figures(records),
+      };
+    }),
+    unpriced: models.filter((model) => !prices.rate(model)),
+  };
+}
+
+function figuresOf(records: readonly SettledOperation[], prices: PriceTable): AccountingFigures {
+  let tokens = NONE;
+  let delegated = NONE;
+  let charged: number | undefined;
+  let agentMs = 0;
+  const agents = new Map<
+    string,
+    { known: boolean; priced: boolean; billed: boolean; cost: number }
+  >();
+  for (const record of records) {
+    const id = agentOf(record);
+    const agent = agents.get(id) ?? {
+      known: true,
+      priced: true,
+      billed: record.billing !== "unknown",
+      cost: 0,
+    };
+    agents.set(id, agent);
+    if (record.deliveredAt !== undefined && record.settledAt !== undefined) {
+      agentMs += Date.parse(record.settledAt) - Date.parse(record.deliveredAt);
+    }
+    // Another currency would need converting first; until then its charge is an unknown one.
+    if (record.charged?.currency === "USD") charged = (charged ?? 0) + record.charged.amount;
+    else if (record.charged) agent.billed = false;
+    if (!record.spend) {
+      agent.known = false;
+      agent.priced = false;
+      continue;
+    }
+    for (const spend of record.spend) {
+      tokens = addTokens(tokens, spend.tokens);
+      if (spend.delegated) delegated = addTokens(delegated, spend.tokens);
+      const rate = prices.rate(spend.model);
+      if (rate) agent.cost += costOf(spend.tokens, rate);
+      else agent.priced = false;
+    }
+  }
+  const counts = [...agents.values()];
+  let estimate: number | undefined;
+  for (const agent of counts) {
+    // A partly priced agent adds what was priced; a fully priced one makes even a zero known.
+    if (agent.priced || agent.cost > 0) estimate = (estimate ?? 0) + agent.cost;
+  }
+  return {
+    agents: agents.size,
+    agentMs,
+    tokens,
+    delegated,
+    ...(estimate === undefined ? {} : { estimate }),
+    ...(charged === undefined ? {} : { charged }),
+    known: counts.filter((agent) => agent.known).length,
+    priced: counts.filter((agent) => agent.priced).length,
+    billed: counts.filter((agent) => agent.billed).length,
+  };
+}
+
+function decisionFigures(records: readonly SettledDecision[], prices: PriceTable): DecisionFigures {
+  let input = 0;
+  let output = 0;
+  let estimate: number | undefined;
+  let charged: number | undefined;
+  let known = 0;
+  let priced = 0;
+  let attempts = 0;
+  for (const record of records) {
+    attempts += record.attempts;
+    // Another currency would need converting first; until then its charge is not counted.
+    if (record.charged?.currency === "USD") charged = (charged ?? 0) + record.charged.amount;
+    if (!record.tokens) continue;
+    known += 1;
+    input += record.tokens.input;
+    output += record.tokens.output;
+    const rate = prices.rate(decisionModelOf(record));
+    if (!rate) continue;
+    priced += 1;
+    estimate = (estimate ?? 0) + costOf(decisionTokens(record.tokens), rate);
+  }
+  return {
+    calls: records.length,
+    attempts,
+    tokens: { input, output },
+    ...(estimate === undefined ? {} : { estimate }),
+    ...(charged === undefined ? {} : { charged }),
+    known,
+    priced,
+  };
+}
+
+function withDecisions(
+  agents: ModelFigures,
+  answered: readonly SettledDecision[],
+  prices: PriceTable,
+): ModelFigures {
+  let tokens = agents.tokens;
+  for (const record of answered) tokens = addTokens(tokens, decisionTokens(record.tokens!));
+  const rate = prices.rate(agents.model);
+  return {
+    ...agents,
+    decisionCalls: answered.length,
+    tokens,
+    ...(rate ? { estimate: costOf(tokens, rate) } : {}),
+  };
+}
+
+function decisionTokens(tokens: { input: number; output: number }): TokenUsage {
+  return { ...NONE, input: tokens.input, output: tokens.output };
+}
+
+/** Priced as the model that answered, when one did: an alias can move, and so can its price. */
+function decisionModelOf(record: SettledDecision): string {
+  return record.snapshot ?? record.model;
+}
+
+function decisionPrefixStageOf(record: SettledDecision): string {
+  return [...record.callPath, prefixOf(record.key)].join("/");
+}
+
+function modelFigures(
+  model: string,
+  usage: readonly SettledOperation[],
+  prices: PriceTable,
+): ModelFigures {
+  const rate = prices.rate(model);
+  const agents = new Set<string>();
+  let tokens = NONE;
+  let delegated = NONE;
+  for (const record of usage) {
+    for (const spend of record.spend ?? []) {
+      if (spend.model !== model) continue;
+      agents.add(agentOf(record));
+      tokens = addTokens(tokens, spend.tokens);
+      if (spend.delegated) delegated = addTokens(delegated, spend.tokens);
+    }
+  }
+  return {
+    model,
+    agents: agents.size,
+    tokens,
+    delegated,
+    ...(rate ? { estimate: costOf(tokens, rate) } : {}),
+  };
+}
+
+/** An agent is its key within its call: the same key in two nested calls is two agents. */
+function agentOf(record: SettledOperation): string {
+  return JSON.stringify([record.callPath, record.agent]);
+}
+
+function workflowStageOf(record: { stage?: string }): string {
+  return record.stage ?? NO_STAGE;
+}
+
+/** A stable sort's order otherwise, with `(no stage)` last. */
+function noStageLast(a: string, b: string): number {
+  return Number(a === NO_STAGE) - Number(b === NO_STAGE);
+}
+
+function prefixStageOf(record: SettledOperation): string {
+  return [...record.callPath, prefixOf(record.agent)].join("/");
+}
+
+function prefixOf(key: string): string {
+  const separator = key.indexOf(":");
+  return separator === -1 ? key : key.slice(0, separator);
+}
+
+function spanOf(
+  records: readonly SettledOperation[],
+  decisions: readonly SettledDecision[] = [],
+): number {
+  const starts = [
+    ...records.flatMap((record) =>
+      record.deliveredAt === undefined ? [] : [Date.parse(record.deliveredAt)],
+    ),
+    ...decisions.map((record) => Date.parse(record.startedAt)),
+  ];
+  const ends = [
+    ...records.flatMap((record) =>
+      record.settledAt === undefined ? [] : [Date.parse(record.settledAt)],
+    ),
+    ...decisions.map((record) => Date.parse(record.settledAt)),
+  ];
+  return starts.length === 0 || ends.length === 0
+    ? 0
+    : Math.max(0, Math.max(...ends) - Math.min(...starts));
+}
+
+function unique<T>(values: readonly T[]): T[] {
+  return [...new Set(values)];
+}
+
+/** What an attempt's record keeps of its run's accounting: the totals and stages, not who spent it. */
+export function attemptAccounting({
+  basis,
+  wallMs,
+  grouping,
+  billing,
+  totals,
+  byStage,
+  unpriced,
+}: RunAccounting): AttemptAccounting {
+  return { basis, wallMs, grouping, billing, totals, byStage, unpriced };
+}
+
+/**
+ * A run's attempts summed, each estimate as its attempt recorded it, under the last one's basis:
+ * its total, and each stage's across the attempts that ran it. Once any attempt grouped by stages, what another grouped by prefix, having failed
+ * before it entered one, ran between stages.
+ */
+export function sumAttempts(attempts: readonly AttemptAccounting[]): AttemptAccounting {
+  const grouping = attempts.some((attempt) => attempt.grouping === "stages") ? "stages" : "prefix";
+  const byStage = new Map<string, RunAccounting["byStage"][number]>();
+  for (const attempt of attempts) {
+    for (const row of attempt.byStage) {
+      const stage = grouping === attempt.grouping ? row.stage : NO_STAGE;
+      const before = byStage.get(stage);
+      byStage.set(
+        stage,
+        before
+          ? { ...addFigures(before, row), stage, spanMs: before.spanMs + row.spanMs }
+          : { ...row, stage },
+      );
+    }
+  }
+  const billings = unique(attempts.map((attempt) => attempt.billing)).filter(
+    (billing) => billing !== "unknown",
+  );
+  return {
+    basis: attempts.at(-1)?.basis ?? "",
+    wallMs: attempts.reduce((sum, attempt) => sum + attempt.wallMs, 0),
+    grouping,
+    billing: billings.length === 0 ? "unknown" : billings.length === 1 ? billings[0]! : "mixed",
+    totals: attempts.map((attempt) => attempt.totals).reduce(addFigures, ZERO),
+    byStage: [...byStage.values()].sort((a, b) => noStageLast(a.stage, b.stage)),
+    unpriced: unique(attempts.flatMap((attempt) => attempt.unpriced)).sort(),
+  };
+}
+
+const ZERO: AccountingFigures = {
+  agents: 0,
+  agentMs: 0,
+  tokens: NONE,
+  delegated: NONE,
+  known: 0,
+  priced: 0,
+  billed: 0,
+};
+
+function addFigures(left: AccountingFigures, right: AccountingFigures): AccountingFigures {
+  const decisions =
+    left.decisions && right.decisions
+      ? addDecisions(left.decisions, right.decisions)
+      : (left.decisions ?? right.decisions);
+  return {
+    agents: left.agents + right.agents,
+    agentMs: left.agentMs + right.agentMs,
+    tokens: addTokens(left.tokens, right.tokens),
+    delegated: addTokens(left.delegated, right.delegated),
+    ...addOptional("estimate", left, right),
+    ...addOptional("charged", left, right),
+    known: left.known + right.known,
+    priced: left.priced + right.priced,
+    billed: left.billed + right.billed,
+    ...(decisions ? { decisions } : {}),
+  };
+}
+
+function addDecisions(left: DecisionFigures, right: DecisionFigures): DecisionFigures {
+  return {
+    calls: left.calls + right.calls,
+    attempts: left.attempts + right.attempts,
+    tokens: {
+      input: left.tokens.input + right.tokens.input,
+      output: left.tokens.output + right.tokens.output,
+    },
+    ...addOptional("estimate", left, right),
+    ...addOptional("charged", left, right),
+    known: left.known + right.known,
+    priced: left.priced + right.priced,
+  };
+}
+
+/** A sum of what either side knows; absent only when neither does. */
+function addOptional<K extends "estimate" | "charged">(
+  field: K,
+  left: { [P in K]?: number },
+  right: { [P in K]?: number },
+): { [P in K]?: number } {
+  if (left[field] === undefined && right[field] === undefined) return {};
+  return { [field]: (left[field] ?? 0) + (right[field] ?? 0) } as { [P in K]?: number };
+}

package/src/accounting/tokens.ts

@@ -0,0 +1,34 @@
+import type { ModelSpend, TokenUsage } from "@agentswf/contract/records";
+
+/** The optional classes stay absent unless one side reports them. */
+export function addTokens(left: TokenUsage, right: TokenUsage): TokenUsage {
+  const optional = (field: "cacheWrite1h" | "reasoning") =>
+    left[field] === undefined && right[field] === undefined
+      ? {}
+      : { [field]: (left[field] ?? 0) + (right[field] ?? 0) };
+  return {
+    input: left.input + right.input,
+    cacheRead: left.cacheRead + right.cacheRead,
+    cacheWrite: left.cacheWrite + right.cacheWrite,
+    ...optional("cacheWrite1h"),
+    output: left.output + right.output,
+    ...optional("reasoning"),
+  };
+}
+
+/** One entry per model and per who spent it, the agent or its subagents. */
+export function spendOf(
+  records: readonly { model: string; delegated: boolean; tokens: TokenUsage }[],
+): ModelSpend[] {
+  const groups = new Map<string, ModelSpend>();
+  for (const record of records) {
+    const group = JSON.stringify([record.model, record.delegated]);
+    const seen = groups.get(group);
+    groups.set(group, {
+      model: record.model,
+      delegated: record.delegated,
+      tokens: seen ? addTokens(seen.tokens, record.tokens) : { ...record.tokens },
+    });
+  }
+  return [...groups.values()];
+}

package/src/agent-launcher.ts

@@ -0,0 +1,127 @@
+import { chmod, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { basename, dirname, join, resolve } from "node:path";
+import { type AgentDoor, shellQuote } from "@agentswf/sandbox";
+
+/** bun loads the `.env` of the directory it starts in: an agent's, which is none of `wf`'s. */
+const NO_ENV = "--no-env-file";
+
+/**
+ * The agent is given a path to run, and nothing else. Every other channel we could deliver a
+ * return address on has turned out to be a harness's private business: a Codex pane executes its
+ * tool commands in a different process from the one Herdr launched, so neither the environment nor
+ * the `PATH` of that pane reaches them. A prompt does reach them, because carrying prompts is the
+ * one thing every harness must do.
+ *
+ * The launcher holds the socket, so nothing secret has to survive that trip, and the connection
+ * is what identifies the agent — no id it types can claim to be somebody else. It is not
+ * isolation: every agent runs as the same user as the engine, so one that goes looking for a
+ * sibling's socket can still find it. Separating those needs a uid per agent.
+ */
+export async function installAgentLauncher(
+  directory: string,
+  endpoint: string,
+  /**
+   * The variable naming the native session, passed on with every call. The harness sets it in the
+   * shell that runs the agent's tool call, which the pane's own environment never reaches.
+   */
+  sessionEnv?: string,
+): Promise<string> {
+  const command = await resolveAgentCommand();
+  return writeLauncher(directory, [process.execPath, NO_ENV, command], endpoint, sessionEnv);
+}
+
+/**
+ * A sandboxed agent's door: the same launcher, running the bundled `wf` with the host's bun by
+ * its real path, since a sandbox reads neither the workspace's sources nor bun's links under `~`.
+ * A box copies `boxScript` to the launcher's path, which runs the bundle with the box's own bun.
+ */
+export async function installSandboxedDoor(
+  directory: string,
+  endpoint: string,
+  /** The bundled `wf`'s source, written beside the launcher. */
+  source: string,
+  sessionEnv?: string,
+): Promise<AgentDoor> {
+  const bun = await realpath(process.execPath);
+  await mkdir(directory, { recursive: true });
+  // Real paths, as a sandbox's rules match them: `/tmp` is `/private/tmp` on macOS.
+  const real = await realpath(directory);
+  const socket = join(real, basename(endpoint));
+  // In the agent's own directory: bun will not load a module from the control plane's, which is
+  // not listable so that no agent can find another's socket.
+  const bundle = join(real, "wf.js");
+  await writeFile(bundle, source, { mode: 0o500 });
+  const launcher = await writeLauncher(real, [bun, NO_ENV, bundle], socket, sessionEnv);
+  return {
+    endpoint: socket,
+    launcher,
+    // A box copies it to the launcher's path, the one it names itself by.
+    boxScript: launcherScript(["bun", NO_ENV, bundle], socket, sessionEnv, launcher),
+    bundle,
+    reads: [bun, bundle],
+  };
+}
+
+/**
+ * `wf` as one file's source, which a sandbox can read where it cannot read this workspace. Built by
+ * a `bun build` of its own: in process, the bundler resolved packages against the test runner's
+ * state and missed the workspace's links.
+ */
+export async function buildAgentBundle(): Promise<string> {
+  const entry = await resolveAgentCommand();
+  const built = Bun.spawn({
+    cmd: [process.execPath, "build", entry, "--target=bun"],
+    cwd: dirname(entry),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [code, bundle, stderr] = await Promise.all([
+    built.exited,
+    new Response(built.stdout).text(),
+    new Response(built.stderr).text(),
+  ]);
+  if (code !== 0) throw new Error(`could not bundle wf: ${stderr.trim().slice(0, 400)}`);
+  return bundle;
+}
+
+async function writeLauncher(
+  directory: string,
+  command: readonly string[],
+  endpoint: string,
+  sessionEnv: string | undefined,
+): Promise<string> {
+  await mkdir(directory, { recursive: true });
+  await chmod(directory, 0o700);
+  const path = join(directory, "wf");
+  // Not writable, so an agent that redirects into its own launcher fails rather than replacing its
+  // only way to answer. A `chmod` still gets past it; a sandbox denies the write outright.
+  await writeFile(path, launcherScript(command, endpoint, sessionEnv, path), { mode: 0o500 });
+  await chmod(path, 0o500);
+  return path;
+}
+
+function launcherScript(
+  command: readonly string[],
+  endpoint: string,
+  sessionEnv: string | undefined,
+  /** Its own path, which `wf` names in what it prints, as an agent must type it. */
+  path: string,
+): string {
+  if (sessionEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(sessionEnv)) {
+    throw new Error(`not an environment variable name: ${sessionEnv}`);
+  }
+  const session = sessionEnv ? ` --session "\${${sessionEnv}:-}"` : "";
+  return `#!/bin/sh\nexec ${command.map(shellQuote).join(" ")} --at ${shellQuote(endpoint)} --as ${shellQuote(path)}${session} "$@"\n`;
+}
+
+async function resolveAgentCommand(): Promise<string> {
+  const require = createRequire(import.meta.url);
+  const manifestPath = require.resolve("@agentswf/wf/package.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as {
+    bin?: string | Record<string, string>;
+  };
+  const relative = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.wf;
+  if (!relative) throw new Error("@agentswf/wf does not publish the wf command");
+  return resolve(dirname(manifestPath), relative);
+}

package/src/allowance-command.ts

@@ -0,0 +1,105 @@
+import {
+  ALLOWANCE_VERSION,
+  type AllowanceReport,
+  type AllowanceWindow,
+  type HarnessAllowance,
+} from "@agentswf/contract/records";
+import { HARNESS_NAMES, type Harness } from "@agentswf/harness";
+import { PLAN_BASIS, planPrice } from "./accounting/plans";
+
+export const allowanceUsage = [
+  "usage: awf allowance [harness...] [--json]",
+  "",
+  "What is left of each harness's plan, as the harness itself shows it: claude's /usage, codex's",
+  "/status, and cursor's /usage, read in a Herdr pane. Nothing asks a model. Every harness when",
+  `none is named: ${HARNESS_NAMES.join(", ")}.`,
+  "",
+  "A plan's monthly price is the vendor's list price as of the table's date, not what was",
+  `charged: ${PLAN_BASIS}.`,
+  "",
+  `--json prints an ${ALLOWANCE_VERSION} record, the interface for scripts, with the plan as the`,
+  "harness names it and no price; what it prints otherwise is for reading. A harness that could",
+  "not be read says why. Exits 0 once every harness was asked, 2 on a usage error.",
+].join("\n");
+
+export type AllowanceCommand = { harnesses: Harness[]; json: boolean } | "help";
+
+export function parseAllowanceCommand(argv: readonly string[]): AllowanceCommand {
+  const harnesses: Harness[] = [];
+  let json = false;
+  for (const arg of argv) {
+    if (arg === "-h" || arg === "--help") return "help";
+    if (arg === "--json") json = true;
+    else if ((HARNESS_NAMES as readonly string[]).includes(arg)) {
+      if (!harnesses.includes(arg as Harness)) harnesses.push(arg as Harness);
+    } else throw new Error(`unknown harness or option: ${arg}`);
+  }
+  return { harnesses: harnesses.length > 0 ? harnesses : [...HARNESS_NAMES], json };
+}
+
+/** Every harness asked at once: cursor's pane takes seconds the others need not wait for. */
+export async function readReport(
+  harnesses: readonly Harness[],
+  read: (harness: Harness) => Promise<HarnessAllowance>,
+  now: number,
+): Promise<AllowanceReport> {
+  return {
+    version: ALLOWANCE_VERSION,
+    readAt: new Date(now).toISOString(),
+    harnesses: await Promise.all(harnesses.map(read)),
+  };
+}
+
+/** A line per harness, its windows in the order it shows them; a reset they share, said once. */
+export function describeReport(report: AllowanceReport, timeZone?: string): string {
+  const width = Math.max(...report.harnesses.map((each) => each.harness.length)) + 2;
+  const now = Date.parse(report.readAt);
+  return report.harnesses
+    .map((each) => {
+      const said =
+        each.read === "none"
+          ? `no allowance: ${each.reason}`
+          : [
+              ...(each.plan ? [describePlan(each.harness, each.plan, each.tier)] : []),
+              ...sharingReset(each.windows).map((windows) => {
+                const used = windows.map((w) => `${w.label} ${w.usedPercent}%`).join(", ");
+                const resetsAt = windows[0]?.resetsAt;
+                return resetsAt
+                  ? `${used}, resets ${describeTime(Date.parse(resetsAt), now, timeZone)}`
+                  : used;
+              }),
+            ].join(" · ");
+      return `${each.harness.padEnd(width)}${said}`;
+    })
+    .join("\n");
+}
+
+/** The plan as people name it and its price, else as the harness words it. */
+function describePlan(harness: string, plan: string, tier?: string): string {
+  const listed = planPrice(harness, plan, tier);
+  if (!listed) return tier ? `${plan} (${tier})` : plan;
+  return listed.usdPerMonth === undefined
+    ? listed.name
+    : `${listed.name} ($${listed.usdPerMonth}/mo)`;
+}
+
+/** Runs of windows, in order, that reset at the same time. */
+function sharingReset(windows: readonly AllowanceWindow[]): AllowanceWindow[][] {
+  const runs: AllowanceWindow[][] = [];
+  for (const window of windows) {
+    const last = runs.at(-1);
+    if (last && last[0]?.resetsAt === window.resetsAt) last.push(window);
+    else runs.push([window]);
+  }
+  return runs;
+}
+
+/** The time alone today, the day alone at midnight, as a day only resets there. */
+function describeTime(at: number, now: number, timeZone?: string): string {
+  const format = (options: Intl.DateTimeFormatOptions) =>
+    new Intl.DateTimeFormat("en-US", { ...options, ...(timeZone ? { timeZone } : {}) }).format;
+  const day = format({ month: "short", day: "numeric" });
+  const time = format({ hour: "2-digit", minute: "2-digit", hourCycle: "h23" })(at);
+  if (day(at) === day(now)) return time;
+  return time === "00:00" ? day(at) : `${day(at)} ${time}`;
+}