[PUBLISHED ON NPMJS] @takk/treasury@1.0.0

STATUS: PUBLISHED ON NPMJS. This version was published to the npm registry on 2026-07-01T02:25:23Z with provenance attestation. View on npm: https://www.npmjs.com/package/@takk/treasury/v/1.0.0

STATUS: REVIEW REQUIRED, NOT YET ON NPMJS. This GitHub Release was created by the release.yml workflow. The Creator must review the contents (tag, changelog, attached commit, pack-smoke result in the workflow logs) and then explicitly run npm-publish.yml to publish this version to the npm registry.

[1.0.0] - 2026-07-01T01:52:11Z

Initial stable release. Treasury is a zero-runtime-dependency NPM library and CLI that governs the cost of a swarm of Massive Intelligence (IM) agents: it enforces hard per-request, per-task, and per-day USD budgets before a call runs, forecasts the cost of an arrangement of model calls ahead of time, plans prefix-cache reuse only when it pays for itself, and routes cheapest-first through a cascade. The core never reaches the network and never reads the clock on its own; it is deterministic cost arithmetic over a price table, which keeps it provider-agnostic, node-free, and testable offline. Where Sakana's Fugu is priced at the ceiling of the pool it orchestrates and hides what a run will cost, Treasury is the CFO of the swarm: it approves or vetoes spend before it happens, on your own infrastructure, including the EU. This is Briefing 6 of the @Takk8IS open multi-agent ecosystem, the cost and finance satellite.

Added

Treasury facade

• Treasury and createTreasury (@takk/treasury/treasury): the object most callers use. It wraps a price table and a budget ledger and exposes the whole discipline: estimate a single call, forecast an arrangement, authorize a spend against hard caps before it happens, record what was actually spent, simulate a plan without recording it, cache to decide a prefix-cache write, plan a cascade, and report the running spend. A clock is injectable so day boundaries and tests are deterministic.

Pricing

• DEFAULT_PRICE_TABLE, DEFAULT_MODEL_IDS, PRICE_TABLE_AS_OF, withPrices, priceOf, estimateCost, costOf, sumBreakdowns, and totalTokens (@takk/treasury/pricing): sixteen provider price profiles (OpenAI, Anthropic, Google, DeepSeek, Mistral, xAI, and the Sakana Fugu tiers) with input, output, and prefix-cache rates. estimateCost returns an itemised micro-USD breakdown, applying long-context pricing when a call's footprint crosses a provider threshold and billing cached-read and cache-write tokens at their own rates. Prices are reference data as of the table date, fully overridable with withPrices, and Treasury never fetches them over the network.
• priceTableAgeDays, isPriceTableStale, and PRICE_TABLE_MAX_AGE_DAYS (@takk/treasury/pricing): a deterministic staleness check, since an out-of-date table quietly makes every estimate wrong. The caller supplies the time, so nothing reads the clock; refresh the table or pass your own when it ages past the horizon.

Budgets

• BudgetLedger, budgetFromUsd, dayKey, and the budget types (@takk/treasury/budget): hard per-request, per-task, and per-day USD caps. authorize is a pre-flight check that never mutates state and reports the tightest binding cap; record commits an actual spend and fires a one-shot depletion event when a cap is crossed. Day boundaries are UTC and derived from an injectable clock, so the ledger is fully deterministic in tests.

Forecasting

• forecast and the forecast types (@takk/treasury/forecast): given an arrangement, an ordered list of model calls with their expected token usage, returns the total micro-USD cost, a symmetric confidence band from a declared variance, a per-model breakdown, and aggregate token counts. The forecast is exact arithmetic over the token estimates the caller supplies; there is no tokenizer and no network call.

Prefix-cache planning

• breakEvenReuses, cacheEconomics, evaluateCache, shouldCache, CACHE_KILL_RULES, and CACHE_KILL_RULE_COUNT (@takk/treasury/prefixcache): a prefix pays to cache only once it is reused enough to amortise the write premium. breakEvenReuses computes that threshold and returns Infinity when a provider offers no read discount. Nine explicit, inspectable cache-kill rules (below-min-tokens, no-provider-cache, non-deterministic-prefix, system-prompt-changed, toolset-changed, unstable-left-prefix, ttl-expired, below-break-even, unprofitable-write) veto a write, and shouldCache guarantees it never recommends a write that would not pay for itself.

Cascade routing

• planCascade and the cascade types (@takk/treasury/cascade): try the cheapest model first and escalate only when a rung's answer is not accepted. The ladder is ordered cheapest-first by estimated cost, the expected spend is weighted by per-rung accept probabilities the caller supplies, and a budget, if given, drops the most expensive rungs that full escalation could not afford. It is pure planning: no model is called, nothing is random.

Model Context Protocol

• createTreasuryTools, createForecastTool, createBudgetTool, createCacheTool, and createPricingResource (@takk/treasury/mcp): Treasury as an MCP surface, the treasury_forecast, treasury_budget, and treasury_cache tools plus a readable treasury://pricing resource, as plain objects that register on any MCP server with no SDK dependency. Every handler is deterministic and node-free.

Edge and node

• @takk/treasury/edge: the deterministic, node-free surface. Every cost calculation, forecast, cache decision, and cascade plan runs unchanged on Cloudflare Workers, Vercel Edge, Deno, Bun, and the browser, because none of it touches node: builtins or the network.
• readJsonFile and writeJsonFile (@takk/treasury/node): the only surface that touches node:fs, persisting and reloading plain JSON plans, forecasts, and price tables with an atomic write so a reader never observes a partial file.

Command-line interface

• treasury CLI with forecast, simulate, price, models, cache, and plan. forecast and simulate read a plan file (simulate also checks it against --per-request, --per-task, and --per-day caps); price and models read the price table and surface its as-of date; cache and plan read a context or ladder file. Stable exit codes: 0 success, 2 usage error, 10 file not found, 20 invalid input, 30 budget exceeded. It is an offline simulator, no network.

Engineering

• 60 tests across 11 suites, green on Node 20, 22, and 24. Coverage 97.7% statements, 91.48% branches, 93.82% functions.
• Zero required runtime dependencies. The core is node-free and network-free; money is represented as integer micro-USD so cost sums never drift.
• Dual ESM and CJS builds with type definitions for both, validated by publint and attw --profile node16, with a per-export size budget enforced by size-limit (the root bundle is 5.99 kB brotlied).
• SLSA provenance attestation on every npm release, published through a two-step, review-required CI/CD flow.
• Optional, conceptual peers @takk/caduceus and @takk/coryphaeus, both optional, so Treasury installs and runs standalone.

Release preparation (2026-07-01T02:17:11Z)

These refinements touch the landing page, the diagram, and the docs, not the shipped tarball, whose files
allowlist carries only the build output and the Markdown docs. The public API, the build output, and the test
results are unchanged.

• Enforced the display-name convention across the whole package: Treasury in prose, lowercase treasury only as a
  token (package id, command, url, path, code identifier).
• Redrew assets/treasury-diagram.svg as a four-stage pipeline, forecast an arrangement, authorize it against hard
  budgets, optimize with prefix-cache break-even and cheapest-first cascade, and record the actual spend, with a
  three-audience band for developers, enthusiasts, and investors, on the shared design system, rendered and visually
  verified.
• Regenerated the Open Graph card (assets/og-image.svg, .png, .jpg) with the current headline and metrics.
• Corrected documentation-versus-code mismatches found by an adversarial audit: the CLI exit-code table on the
  landing page, the forecast result fields (lowMicros, highMicros, perModel), the MCP example (resource
  singular, tool lookup by name, flat tool input), and the price-override example (createTreasury({ table: withPrices(...) })). Refreshed the published numbers to the current 60 tests and coverage.

Not in 1.0 (non-goals)

• No network price synchronisation. The default price table is reference data; keep it current or pass your own with withPrices. Treasury never fetches prices.
• No tokenizer. The forecast is exact arithmetic over the token counts you provide; estimating those counts is the caller's job.
• No learned routing. The 1.0 cascade uses caller-supplied accept probabilities; bandit-optimal cost routing is on the roadmap for a later version.
• No hosted dashboard and no telemetry. Treasury is the deterministic cost-control substrate; a hosted panel is the roadmap. It collects and transmits nothing.