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

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@agentswf/engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "description": "agents.wf: the engine that runs workflows made of coding agents",
+  "license": "MIT",
+  "homepage": "https://github.com/romanlv/agentswf",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/romanlv/agentswf.git",
+    "directory": "packages/engine"
+  },
+  "type": "module",
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "bin": {
+    "awf": "./src/operator-cli.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./testing": "./src/testing.ts",
+    "./workflow-testing": "./src/workflow-testing/index.ts",
+    "./cli": "./src/operator-cli.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.eval.ts",
+    "!src/**/fixtures"
+  ],
+  "dependencies": {
+    "@agentswf/wf": "0.1.0-beta.0",
+    "@agentswf/contract": "0.1.0-beta.0",
+    "@agentswf/harness": "0.1.0-beta.0",
+    "@agentswf/sandbox": "0.1.0-beta.0",
+    "typebox": "^1.3.34"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/accounting/format.ts

@@ -0,0 +1,252 @@
+import type {
+  AccountingFigures,
+  AttemptAccounting,
+  DecisionFigures,
+} from "@agentswf/contract/records";
+import { PUBLISHED_PRICES } from "./prices";
+
+type Slice = AttemptAccounting["byStage"][number];
+
+/**
+ * What an attempt cost: a line of its figures, its decisions on a line of their own when it asked
+ * any, then a row per stage or group when there is more than one. `stages: false` leaves a
+ * workflow's stage rows to a view that shows them beside its stages; a run without stages keeps its
+ * groups. A stage that opened no agent and asked nothing has no row, as it has no figures beside
+ * it in that view. Gaps are named, never shown as zero; what is complete is left to the record.
+ */
+export function describeAccounting(
+  accounting: AttemptAccounting,
+  options: { stages?: boolean } = {},
+): string[] {
+  const staged = accounting.grouping === "stages";
+  const rows =
+    accounting.byStage.length > 1 && (!staged || options.stages !== false)
+      ? accounting.byStage.filter((row) => !staged || row.agents > 0 || row.decisions)
+      : [];
+  const width = Math.max(0, ...rows.map(({ stage }) => stage.length));
+  return [
+    describeTotals(accounting),
+    ...describeDecisionLine(accounting),
+    ...rows.map((row) => sliceRow(row, width)),
+  ];
+}
+
+/**
+ * The agents' count, the time, then their tokens, estimate, billing and gaps. A run that opened no
+ * agent is its time and what went unpriced; one that asked decisions says it opened no agent, so
+ * they are not taken for agents.
+ */
+function describeTotals(accounting: AttemptAccounting): string {
+  const { totals } = accounting;
+  const basis = shortBasis(accounting.basis);
+  const took = duration(accounting.wallMs);
+  const unpriced =
+    accounting.unpriced.length === 0 ? [] : [`unpriced: ${accounting.unpriced.join(", ")}`];
+  if (totals.agents === 0) {
+    return [...(totals.decisions ? [plural(0, "agent")] : []), took, ...unpriced].join(" · ");
+  }
+  return [
+    plural(totals.agents, "agent"),
+    took,
+    tokensOf(totals),
+    ...(totals.estimate === undefined ? [] : [`${estimate(totals.estimate)} at ${basis}`]),
+    ...(totals.charged === undefined ? [] : [`${usd(totals.charged)} charged`]),
+    accounting.billing,
+    ...(totals.billed < totals.agents ? [`billing known ${totals.billed}/${totals.agents}`] : []),
+    ...usageGap(totals),
+    ...gaps(totals),
+    ...unpriced,
+  ].join(" · ");
+}
+
+/**
+ * A run of several attempts, in brief: how many, those whose cost is unknown, by why, how long in
+ * all, and the estimate when any agent ran. `unknown` counts the attempts with no cost recorded:
+ * interrupted, or ended without one, as an older record may be.
+ */
+export function describeAttempts(
+  sum: AttemptAccounting,
+  attempts: number,
+  unknown: { interrupted: number; ended: number },
+): string {
+  const why = [
+    ...(unknown.interrupted > 0 ? [`${unknown.interrupted} interrupted`] : []),
+    ...(unknown.ended > 0 ? [`${unknown.ended} ended without a cost record`] : []),
+  ];
+  const gap = why.length > 0 ? ` (${why.join(", ")}, cost unknown)` : "";
+  const priced =
+    sum.totals.agents > 0 && sum.totals.estimate !== undefined
+      ? [estimate(sum.totals.estimate)]
+      : [];
+  return `run: ${[`${attempts} attempts${gap}`, duration(sum.wallMs), ...priced].join(", ")}`;
+}
+
+function describeDecisionLine(accounting: AttemptAccounting): string[] {
+  const { decisions } = accounting.totals;
+  return decisions ? [describeDecisions(decisions, shortBasis(accounting.basis))] : [];
+}
+
+/**
+ * A workflow's stages, each to what its agents and decisions cost, for the view to show beside
+ * them; a stage that opened none and asked nothing is left out, not shown at zero.
+ */
+export function stageFigures(accounting: AttemptAccounting): Map<string, string> {
+  if (accounting.grouping !== "stages") return new Map();
+  return new Map(
+    accounting.byStage.flatMap((stage) => {
+      const figures = [
+        ...(stage.agents === 0
+          ? []
+          : [
+              plural(stage.agents, "agent"),
+              tokensOf(stage),
+              ...priced(stage),
+              ...agentGaps(stage),
+            ]),
+        ...(stage.decisions ? [plural(stage.decisions.calls, "decision")] : []),
+        ...decisionCost(stage),
+      ];
+      return figures.length === 0 ? [] : [[stage.stage, figures.join(" · ")] as const];
+    }),
+  );
+}
+
+/**
+ * A table's row: the agents and decisions counted together, `0 agents` for a slice with neither,
+ * then its time, and the estimate alone where there is one, as the row has room for.
+ */
+function sliceRow(stage: Slice, width: number): string {
+  const counted = [
+    ...(stage.agents === 0 && stage.decisions ? [] : [plural(stage.agents, "agent")]),
+    ...(stage.decisions ? [plural(stage.decisions.calls, "decision")] : []),
+  ].join(", ");
+  const agents =
+    stage.agents === 0
+      ? []
+      : [
+          ...(stage.estimate === undefined ? [tokensOf(stage)] : priced(stage)),
+          ...agentGaps(stage),
+        ];
+  return [
+    `  ${stage.stage.padEnd(width)}  ${counted}`,
+    duration(stage.spanMs),
+    ...agents,
+    ...decisionCost(stage),
+  ].join(" · ");
+}
+
+function tokensOf(figures: AccountingFigures): string {
+  return figures.known === 0 ? "no usage known" : plural(total(figures), "token", count);
+}
+
+function priced(stage: Slice): string[] {
+  return stage.estimate === undefined ? [] : [estimate(stage.estimate)];
+}
+
+function agentGaps(figures: AccountingFigures): string[] {
+  return [...usageGap(figures), ...gaps(figures)];
+}
+
+function usageGap(figures: AccountingFigures): string[] {
+  return figures.known < figures.agents && figures.known > 0
+    ? [`usage known ${figures.known}/${figures.agents}`]
+    : [];
+}
+
+/** A slice's decisions past their count: their estimate, apart from its agents', and gaps. */
+function decisionCost(stage: Slice): string[] {
+  const { decisions } = stage;
+  if (!decisions) return [];
+  const cost =
+    decisions.estimate === undefined
+      ? decisions.known === 0
+        ? ["no usage known"]
+        : []
+      : [
+          stage.agents === 0
+            ? estimate(decisions.estimate)
+            : `${estimate(decisions.estimate)} in decisions`,
+        ];
+  return [...cost, ...decisionGaps(decisions)];
+}
+/** The published table by its kind alone, its date being in the record; any other table in full. */
+function shortBasis(basis: string): string {
+  return basis === PUBLISHED_PRICES.basis ? "list prices" : basis;
+}
+
+/** Decisions are not agents: their calls, tokens and cost stay on a line of their own. */
+function describeDecisions(decisions: DecisionFigures, basis: string): string {
+  const tokens = decisions.tokens.input + decisions.tokens.output;
+  return [
+    `  ${plural(decisions.calls, "decision")}`,
+    ...(decisions.attempts > decisions.calls ? [plural(decisions.attempts, "request")] : []),
+    decisions.known === 0 ? "no usage known" : plural(tokens, "token", count),
+    ...(decisions.estimate === undefined ? [] : [`${estimate(decisions.estimate)} at ${basis}`]),
+    ...(decisions.charged === undefined ? [] : [`${usd(decisions.charged)} charged`]),
+    ...decisionGaps(decisions),
+  ].join(" · ");
+}
+
+/** As for agents: unknown usage first, then usage known but not all priced. */
+function decisionGaps(decisions: DecisionFigures): string[] {
+  return [
+    ...(decisions.known < decisions.calls
+      ? [`usage known ${decisions.known}/${decisions.calls}`]
+      : []),
+    ...(decisions.priced < decisions.known
+      ? [`priced ${decisions.priced}/${decisions.calls}`]
+      : []),
+  ];
+}
+
+function total({ tokens }: AccountingFigures): number {
+  return tokens.input + tokens.cacheRead + tokens.cacheWrite + tokens.output;
+}
+
+/** An agent whose usage is known but not all priced adds only its priced part to an estimate. */
+function gaps(figures: AccountingFigures): string[] {
+  return figures.priced < figures.known ? [`fully priced ${figures.priced}/${figures.agents}`] : [];
+}
+
+function plural(amount: number, noun: string, show: (amount: number) => string = String): string {
+  return `${show(amount)} ${noun}${amount === 1 ? "" : "s"}`;
+}
+
+/** A span as a person reads it: `42s`, `3m 05s`, `1h 02m`. */
+export function duration(milliseconds: number): string {
+  const seconds = Math.max(0, Math.round(milliseconds / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${String(seconds % 60).padStart(2, "0")}s`;
+  return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m`;
+}
+
+/** How long ago, for a person: `just now`, `5m ago`, `3h ago`, `2d ago`. */
+export function ago(ms: number): string {
+  if (!Number.isFinite(ms)) return "at an unknown time";
+  if (ms < 60_000) return "just now";
+  const minutes = Math.round(ms / 60_000);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  return hours < 48 ? `${hours}h ago` : `${Math.round(hours / 24)}d ago`;
+}
+
+function count(tokens: number): string {
+  if (tokens >= 999_500) return `${(tokens / 1_000_000).toFixed(2)}M`;
+  if (tokens >= 1_000) return `${Math.round(tokens / 1_000)}k`;
+  return String(tokens);
+}
+
+function usd(amount: number): string {
+  return belowCent(amount) ? "<$0.01" : `$${amount.toFixed(2)}`;
+}
+
+/** Marked approximate, unless `<` already says so. */
+function estimate(amount: number): string {
+  return belowCent(amount) ? usd(amount) : `~${usd(amount)}`;
+}
+
+/** A real cost too small to show in cents is not shown as nothing. */
+function belowCent(amount: number): boolean {
+  return amount > 0 && amount < 0.005;
+}

package/src/accounting/plans.ts

@@ -0,0 +1,38 @@
+/**
+ * What each plan costs a month, by the name its harness reports, as the vendors listed it on the
+ * date of `PLAN_BASIS`. Policy, not observation: a record keeps the plan's name, and a price is
+ * looked up when it is shown. A plan not listed, or listed without a price, shows none.
+ */
+export const PLAN_BASIS = "plans 2026-10-05";
+
+type Listed = { name: string; usdPerMonth?: number };
+
+const PLANS: Readonly<Record<string, (plan: string, tier?: string) => Listed | undefined>> = {
+  // `claude auth status` says `pro` or `max`; Max's tier is in its account: 5x is $100, 20x $200.
+  claude: (plan, tier) => {
+    if (plan === "pro") return { name: "Pro", usdPerMonth: 20 };
+    if (plan !== "max") return undefined;
+    if (tier?.endsWith("_max_20x")) return { name: "Max 20x", usdPerMonth: 200 };
+    if (tier?.endsWith("_max_5x")) return { name: "Max 5x", usdPerMonth: 100 };
+    return { name: "Max" };
+  },
+  // OpenAI's own product names for its plan types: `prolite` is Pro 100, `promax` Pro 500.
+  codex: (plan) =>
+    (
+      ({
+        free: { name: "Free", usdPerMonth: 0 },
+        go: { name: "Go", usdPerMonth: 8 },
+        plus: { name: "Plus", usdPerMonth: 20 },
+        prolite: { name: "Pro 100", usdPerMonth: 100 },
+        pro: { name: "Pro 200", usdPerMonth: 200 },
+        promax: { name: "Pro 500", usdPerMonth: 500 },
+      }) as Record<string, Listed>
+    )[plan],
+  // A team seat is Standard or Premium, $40 or $120, and `/usage` does not say which.
+  cursor: (plan) => (plan === "Team" ? { name: "Team" } : undefined),
+};
+
+/** The plan as people name it and its monthly price, where `PLAN_BASIS` lists them. */
+export function planPrice(harness: string, plan: string, tier?: string): Listed | undefined {
+  return Object.hasOwn(PLANS, harness) ? PLANS[harness]!(plan, tier) : undefined;
+}

package/src/accounting/prices.ts

@@ -0,0 +1,98 @@
+import type { TokenUsage } from "@agentswf/contract/records";
+
+/** USD per million tokens, for every class a request can be billed in. */
+export type ModelRate = {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+};
+
+export type PriceTable = {
+  /** Names the table a figure came from; figures from two bases are never compared. */
+  basis: string;
+  rate(model: string): ModelRate | undefined;
+};
+
+/** Anthropic prices cache writes at 1.25x input for five minutes and 2x for an hour. */
+function anthropic(input: number, output: number, read = 0.1): ModelRate {
+  return {
+    input,
+    output,
+    cacheRead: input * read,
+    cacheWrite5m: input * 1.25,
+    cacheWrite1h: input * 2,
+  };
+}
+
+/** OpenAI lists cached input and, for its newer models, a cache-write rate of 1.25x input. */
+function openai(input: number, cached: number, output: number, write = input * 1.25): ModelRate {
+  return { input, output, cacheRead: cached, cacheWrite5m: write, cacheWrite1h: write };
+}
+
+/**
+ * List prices, read on 2026-09-23 (Claude Sonnet 5.5 on 2026-09-29, GPT-6.1 Sol on 2026-10-01, Claude Haiku 5.5 on 2026-10-07) from https://platform.claude.com/docs/en/about-claude/pricing
+ * and https://developers.openai.com/api/docs/pricing, and on 2026-09-26 from OpenRouter for Jev. A subscription is not charged per token,
+ * but its allowance is drawn down roughly in proportion to these, so they price any run the same
+ * way whoever pays for it.
+ *
+ * Not modelled: OpenAI's long-context rates (2x input and 1.5x output, on gpt-5.6 and gpt-6 past
+ * a threshold, and on gpt-5.5 past 272K), and Claude Haiku 5.5's 5x rate on prompts past 100K, so
+ * a very long session on either is under-estimated.
+ */
+const RATES: Record<string, ModelRate> = {
+  "claude-fable-5-1": anthropic(10, 50, 0.025),
+  "claude-fable-5": anthropic(10, 50),
+  "claude-opus-5-5": anthropic(4, 20, 0.05),
+  "claude-opus-5": anthropic(5, 25),
+  "claude-opus-4-8": anthropic(5, 25),
+  "claude-opus-4-7": anthropic(5, 25),
+  "claude-opus-4-6": anthropic(5, 25),
+  "claude-opus-4-5": anthropic(5, 25),
+  "claude-sonnet-5-5": anthropic(2, 10, 0.05),
+  "claude-sonnet-5": anthropic(2, 10),
+  "claude-sonnet-4-6": anthropic(3, 15),
+  "claude-sonnet-4-5": anthropic(3, 15),
+  "claude-haiku-5-5": anthropic(0.1, 0.5),
+  "claude-haiku-4-5": anthropic(1, 5),
+  "gpt-6-astra": openai(10, 1, 50),
+  "gpt-6.1-sol": openai(2, 0.1, 10),
+  "gpt-6-sol": openai(2, 0.2, 10),
+  "gpt-6-luna": openai(0.1, 0.01, 0.5),
+  "gpt-5.6-sol": openai(4, 0.4, 20),
+  "gpt-5.6-terra": openai(2, 0.2, 12),
+  "gpt-5.6-luna": openai(0.2, 0.02, 1.2),
+  // No cache-write charge is listed for these.
+  "gpt-5.5": openai(5, 0.5, 30, 5),
+  "gpt-5.4": openai(2.5, 0.25, 15, 2.5),
+  // OpenRouter's listing, read on 2026-09-26: input only; output is reported and not charged.
+  "typesafe/jev-1.13": { input: 0.042, output: 0, cacheRead: 0, cacheWrite5m: 0, cacheWrite1h: 0 },
+};
+
+/**
+ * A model is priced only as itself: its family id, the id with a release date after it, or either
+ * with a context tag such as `[1m]`. Anything else, even a close sibling such as `claude-opus-5-6`
+ * or `gpt-5.5-pro`, is unpriced rather than priced at a rate that is not its own.
+ */
+function lookup(model: string): ModelRate | undefined {
+  const own = (id: string) => (Object.hasOwn(RATES, id) ? RATES[id] : undefined);
+  const bare = model.replace(/\[[^\]]*\]$/, "");
+  const dated = /^(.+?)-(\d{8}|\d{4}-\d{2}-\d{2})$/.exec(bare);
+  return own(bare) ?? (dated ? own(dated[1]!) : undefined);
+}
+
+export const PUBLISHED_PRICES: PriceTable = { basis: "list prices 2026-10-07", rate: lookup };
+
+/** `cacheWrite1h` is the part of `cacheWrite` with an hour's lifetime; the rest is five minutes. */
+export function costOf(tokens: TokenUsage, rate: ModelRate): number {
+  const hour = Math.min(tokens.cacheWrite, tokens.cacheWrite1h ?? 0);
+  return (
+    (tokens.input * rate.input +
+      tokens.cacheRead * rate.cacheRead +
+      (tokens.cacheWrite - hour) * rate.cacheWrite5m +
+      hour * rate.cacheWrite1h +
+      tokens.output * rate.output) /
+    1_000_000
+  );
+}