Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

chore: bump loop-cost 1.2.0 + loop-context 1.5.0 (cache publish + STATE) (#352)

Cobus Greyling8c51ee848530
diff --git a/RELEASE_NOTES_DRAFT.md b/RELEASE_NOTES_DRAFT.md
index 5730676..c6c9d48 100644
--- a/RELEASE_NOTES_DRAFT.md
+++ b/RELEASE_NOTES_DRAFT.md
@@ -1,23 +1,54 @@
-# Release notes draft — since `loop-context-v1.2.0`
+# Release notes draft — since Discussion #294
-**Status:** Stub for next changelog-drafter run.
+**Status:** Draft for human review ([#332](https://github.com/cobusgreyling/loop-engineering/issues/332)). Edit before publishing a discussion post or tagging packages.
**Last published:** [Discussion #294](https://github.com/cobusgreyling/loop-engineering/discussions/294) (2026-07-16) — `loop-context` 1.2.0, `loop-worktree` 1.1.0.
-**Window:** 2026-07-16 → (next tag)
+**Window:** 2026-07-16 → 2026-07-22
---
## Highlights
-_(changelog-drafter will fill from merges since `loop-context-v1.2.0`)_
+### Prompt caching cost model ([#346](https://github.com/cobusgreyling/loop-engineering/pull/346), [#347](https://github.com/cobusgreyling/loop-engineering/pull/347))
-### Pending npm publish
+- **`loop-cost` 1.2.0** — `--with-caching` scenario + `stable_fraction` on patterns in `registry.yaml` (cache-read discount on stable report/action tokens).
+- **`loop-context` 1.5.0** — `--budget-scenario caching` resolves a cap from the new scenario (shells out with `--with-caching`).
-| Package | PR | What ships |
-|---------|-----|------------|
-| `@cobusgreyling/loop-worktree` **1.2.0** | [#292](https://github.com/cobusgreyling/loop-engineering/pull/292) | Wait queue (`--wait`) + deadlock detection on path locks (@THRISHAL12345) |
-| `@cobusgreyling/loop-gate` **1.0.0** | [#291](https://github.com/cobusgreyling/loop-engineering/pull/291) | Mechanical denylist + auto-merge allowlist from `gate.yaml` (@KhaiTrang1995) |
+```bash
+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --with-caching
+npx @cobusgreyling/loop-context --check --ledger run.json \
+ --budget-from-pattern daily-triage --budget-level L1 --budget-scenario caching
+```
+
+Thanks [@Tusm11](https://github.com/Tusm11).
+
+### Circuit breaker + packages already on npm
+
+| Package | Version | Notes |
+|---------|---------|--------|
+| `@cobusgreyling/loop-context` | **1.4.0** (live) → **1.5.0** (this batch) | Frustration circuit breaker [#337](https://github.com/cobusgreyling/loop-engineering/pull/337); caching scenario this batch |
+| `@cobusgreyling/loop-cost` | **1.1.0** (live) → **1.2.0** (this batch) | Prompt-caching estimate this batch |
+| `@cobusgreyling/loop-audit` | **1.7.0** | Live |
+| `@cobusgreyling/loop-init` | **1.5.0** | Live |
+| `@cobusgreyling/loop-worktree` | **1.2.0** | Wait queue + deadlock detection [#292](https://github.com/cobusgreyling/loop-engineering/pull/292); published |
+| `@cobusgreyling/loop-gate` | **1.0.0** | First publish from [#291](https://github.com/cobusgreyling/loop-engineering/pull/291); live |
+| `@cobusgreyling/goal-init` | **1.0.0** | First publish |
+| `@cobusgreyling/readiness-core` | **1.0.0** | First publish (build before loop-audit in CI) |
+
+### Docs appendices (primitives matrix)
+
+| PR | Contributor | Tool |
+|----|-------------|------|
+| [#351](https://github.com/cobusgreyling/loop-engineering/pull/351) | @shixi-li | Continue.dev (closes #117) |
+| [#350](https://github.com/cobusgreyling/loop-engineering/pull/350) | @adity982 | GitHub Copilot (closes #196) |
+
+### Other notable merges (window)
+
+- `loop-worktree` npm path + macOS gc fix [#204](https://github.com/cobusgreyling/loop-engineering/pull/204)
+- Star-history docs + chart automation [#193](https://github.com/cobusgreyling/loop-engineering/pull/193), [#205](https://github.com/cobusgreyling/loop-engineering/pull/205), [#192](https://github.com/cobusgreyling/loop-engineering/pull/192)
+- Daily triage CI: build readiness-core before loop-audit [#349](https://github.com/cobusgreyling/loop-engineering/pull/349)
+- Community docs/stories: multi-loop coordination, Opencode constraints, Hermes examples
---
@@ -26,4 +57,49 @@ _(changelog-drafter will fill from merges since `loop-context-v1.2.0`)_
```bash
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop-audit . --suggest
-```
\ No newline at end of file
+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --with-caching
+npx @cobusgreyling/loop-worktree list
+```
+
+---
+
+## npm publish checklist (2026-07-22)
+
+| Package | On npm now | This PR / tag | Action |
+|---------|------------|---------------|--------|
+| `@cobusgreyling/loop-cost` | 1.1.0 | **1.2.0** → `loop-cost-v1.2.0` | **Publish after merge** |
+| `@cobusgreyling/loop-context` | 1.4.0 | **1.5.0** → `loop-context-v1.5.0` | **Publish after merge** (depends on cost 1.2.0 for dep range) |
+| `@cobusgreyling/loop-audit` | 1.7.0 | — | No change |
+| `@cobusgreyling/loop-init` | 1.5.0 | — | No change |
+| `@cobusgreyling/loop-worktree` | 1.2.0 | — | Already published |
+| `@cobusgreyling/loop-gate` | 1.0.0 | — | Already published |
+| `@cobusgreyling/goal-init` | 1.0.0 | — | Already published |
+| `@cobusgreyling/readiness-core` | 1.0.0 | — | Already published |
+| `@cobusgreyling/loop-mcp-server` | 1.1.0* | — | No change (*confirm if needed) |
+| `@cobusgreyling/loop-sync` | 1.0.0* | — | No change |
+
+\* Verify with `npm view @cobusgreyling/<pkg> version` before any announce.
+
+### Suggested publish steps
+
+1. Merge this PR (versions + notes + STATE).
+2. Tag and push (triggers release workflows):
+
+```bash
+git tag loop-cost-v1.2.0
+git push origin loop-cost-v1.2.0
+git tag loop-context-v1.5.0
+git push origin loop-context-v1.5.0
+```
+
+3. Confirm Actions → Release loop-cost / Release loop-context are green.
+4. `npm view @cobusgreyling/loop-cost version` → `1.2.0`; same for `loop-context` → `1.5.0`.
+5. Human: fold this draft into discussion/announce for [#332](https://github.com/cobusgreyling/loop-engineering/issues/332) when ready.
+6. Supersedes contributor draft [#348](https://github.com/cobusgreyling/loop-engineering/pull/348) (stale checklist).
+
+---
+
+## Housekeeping
+
+- PR triage 2026-07-22: merged #351/#350; closed #344 superseded; held then superseded #348.
+- Feature PRs must include `package.json` bumps + this checklist row in the same change (lesson from #346/#347 gap).
diff --git a/STATE.md b/STATE.md
index 6c82a47..af7aaca 100644
--- a/STATE.md
+++ b/STATE.md
@@ -1,28 +1,31 @@
# Loop State — loop-engineering reference
-Last run: 2026-07-21T20:30:00Z (scheduled maintenance)
+Last run: 2026-07-22T12:48:31Z (scheduled maintenance — publish checklist + cache bumps + STATE)
## High Priority (loop is acting or waiting on human)
- Maintain loop readiness score ≥ 58 (current: **100**, level **L3**).
-- npm publish in flight this run: `readiness-core` 1.0.0, `goal-init` 1.0.0, `loop-context` 1.4.0 (tags after merge).
-- [#332](https://github.com/cobusgreyling/loop-engineering/issues/332) release prep — week of 2026-07-20 (human changelog/discussion).
+- **Publish after this PR merges:** tag `loop-cost-v1.2.0` and `loop-context-v1.5.0` (prompt-caching work from #346/#347). See `RELEASE_NOTES_DRAFT.md` checklist.
+- [#332](https://github.com/cobusgreyling/loop-engineering/issues/332) release prep / discussion announce — human when notes are ready.
## Watch List
- Contributor failure stories; Post-Merge Cleanup production story
-- Cursor/docs GFI: #220, #223, #224; #117–#120, #147, #173, #195, #196
-- Validate `loop-init --with-foundry` on fresh projects
+- Remaining Cursor/docs GFI: #220, #223, #224; #118–#120, #147, #173, #195 ( #117 via #351, #196 via #350 — done)
+- Validate `loop-init --with-foundry` + `goal-init` on fresh projects
- Optional: StackMap #300, Pluribus #262, loop.js #246
-## Housekeeping (2026-07-21 scheduled maintenance)
+## Open PRs
-- Merged [#338](https://github.com/cobusgreyling/loop-engineering/pull/338) (loop-init lockfile → loop-audit 1.7.0).
-- Merged [#337](https://github.com/cobusgreyling/loop-engineering/pull/337) (loop-context frustration circuit breaker) — bumped to 1.4.0.
-- Added `release-goal-init.yml` + RELEASE.md docs; first publish for `goal-init` + `readiness-core`.
-- Closed draft [#336](https://github.com/cobusgreyling/loop-engineering/pull/336) as superseded.
-- Closed weekly loop report [#320](https://github.com/cobusgreyling/loop-engineering/issues/320) after review.
-- No open PRs after this run; CI green on `main`.
+- None expected after merge of this maintenance PR and close of #348 (superseded).
+- If anything reopens: first-time contributor workflows need `validate`+`audit` approval before merge.
+
+## Housekeeping (2026-07-22)
+
+- **Merged:** #346 loop-cost caching, #347 loop-context caching budget, #349 daily-triage readiness-core build, #350 Copilot appendix, #351 Continue appendix.
+- **Closed:** #344 night STATE draft (superseded); #348 release-notes draft (stale npm table — replaced by this checklist).
+- **Version bumps in this run:** loop-cost **1.2.0**, loop-context **1.5.0** (npm still 1.1.0 / 1.4.0 until tags).
+- Other packages already current on npm: loop-audit 1.7.0, loop-init 1.5.0, loop-worktree 1.2.0, loop-gate 1.0.0, goal-init 1.0.0, readiness-core 1.0.0.
## Recent Noise
@@ -31,8 +34,9 @@ Last run: 2026-07-21T20:30:00Z (scheduled maintenance)
## Post-Run Critique
-- Friction: `goal-init` landed without a release workflow; caught on maintenance.
-- Adjustment: require release workflow + RELEASE.md row in the same PR as any new `tools/*` package.
+- Friction: #346/#347 shipped features without package.json bumps — blocked real npm consumers until this maintenance.
+- Adjustment (reaffirmed): any `tools/*` behavior change PR must include version bump + RELEASE_NOTES_DRAFT row in the same PR.
+- Friction: first-time contributor PRs blocked on workflow approval for required checks — approve early in triage.
---
-Run log: Updated by `.github/workflows/daily-triage.yml`. See `LOOP.md` for cadence and gates.
\ No newline at end of file
+Run log: Updated by daily-triage.yml and scheduled maintenance. See LOOP.md for cadence and gates.
diff --git a/loop-run-log.md b/loop-run-log.md
index aadaf46..3978a5d 100644
--- a/loop-run-log.md
+++ b/loop-run-log.md
@@ -47,3 +47,4 @@ Append one entry per run. Prune entries older than 30 days.
{"run_id":"2026-07-21T12:08:44Z","pattern":"daily-triage","duration_s":180,"items_found":6,"actions_taken":2,"escalations":4,"tokens_estimate":35000,"readiness_score":100,"outcome":"report-only","note":"re-curate after #334; open 315-318,321,323"}
{"run_id":"2026-07-21T12:38:33Z","pattern":"daily-triage","duration_s":90,"items_found":7,"actions_taken":1,"escalations":5,"tokens_estimate":25000,"readiness_score":100,"outcome":"report-only","note":"new PR #335 loop-context breaker; open 315-318,321,323,335"}
{"run_id":"2026-07-21T14:11:50Z","pattern":"daily-triage","duration_s":600,"items_found":7,"actions_taken":5,"escalations":2,"tokens_estimate":40000,"readiness_score":100,"outcome":"report-only","note":"PR triage: merge 316/318/335; close 315; changes-requested 317/321"}
+{"run_id":"2026-07-22T12:48:31Z","pattern":"scheduled-maintenance","duration_s":900,"items_found":4,"actions_taken":4,"escalations":1,"tokens_estimate":40000,"readiness_score":100,"outcome":"acting","note":"bump loop-cost 1.2.0 + loop-context 1.5.0; refresh RELEASE_NOTES checklist; rewrite STATE after #350/#351; supersede #348; tags after merge"}
diff --git a/tools/loop-context/README.md b/tools/loop-context/README.md
index 8c082f1..905089c 100644
--- a/tools/loop-context/README.md
+++ b/tools/loop-context/README.md
@@ -89,7 +89,7 @@ loop-context --check --ledger run.json --budget-from-pattern ci-sweeper --budget
|------|---------|---------|
| `--budget-from-pattern <id>` | none | Pattern id to look up in `loop-cost`'s registry |
| `--budget-level <L1\|L2\|L3>` | `L1` | Readiness level passed to `loop-cost` |
-| `--budget-scenario <realistic\|action\|report>` | `realistic` | Which `loop-cost` scenario to use as the cap |
+| `--budget-scenario <realistic\|action\|report\|caching>` | `realistic` | Which `loop-cost` scenario to use as the cap (`caching` requires `stable_fraction` on the pattern and passes `--with-caching` to `loop-cost`) |
| `--budget-cadence <spec>` | pattern default | Cadence override passed through to `loop-cost` |
| `--budget-conservative` | off | Use the slower cadence in a range (`loop-cost`'s own flag) |
diff --git a/tools/loop-context/dist/budget-resolver.d.ts b/tools/loop-context/dist/budget-resolver.d.ts
index d81724c..7dca039 100644
--- a/tools/loop-context/dist/budget-resolver.d.ts
+++ b/tools/loop-context/dist/budget-resolver.d.ts
@@ -1,4 +1,4 @@
-export type BudgetScenario = 'realistic' | 'action' | 'report';
+export type BudgetScenario = 'realistic' | 'action' | 'report' | 'caching';
export declare const VALID_BUDGET_SCENARIOS: BudgetScenario[];
export declare function assertValidBudgetScenario(scenario: string): asserts scenario is BudgetScenario;
export interface BudgetFromPatternInput {
diff --git a/tools/loop-context/dist/budget-resolver.js b/tools/loop-context/dist/budget-resolver.js
index 624e1c2..f1b85ff 100644
--- a/tools/loop-context/dist/budget-resolver.js
+++ b/tools/loop-context/dist/budget-resolver.js
@@ -4,7 +4,7 @@ import { access } from 'node:fs/promises';
import { spawn } from 'node:child_process';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const PACKAGE_ROOT = path.resolve(__dirname, '..');
-export const VALID_BUDGET_SCENARIOS = ['realistic', 'action', 'report'];
+export const VALID_BUDGET_SCENARIOS = ['realistic', 'action', 'report', 'caching'];
export function assertValidBudgetScenario(scenario) {
if (!VALID_BUDGET_SCENARIOS.includes(scenario)) {
throw new Error(`Invalid --budget-scenario: ${scenario}. Valid: ${VALID_BUDGET_SCENARIOS.join(', ')}`);
@@ -60,6 +60,8 @@ async function invokeLoopCost(input) {
args.push('--cadence', input.cadence);
if (input.conservative)
args.push('--conservative');
+ if (input.scenario === 'caching')
+ args.push('--with-caching');
const { stdout, stderr, code } = await runCostCli(cli, args);
if (code !== 0) {
throw new Error(stderr.trim() || `loop-cost exited with code ${code}.`);
@@ -84,7 +86,10 @@ export async function resolveTokenBudgetFromPattern(input) {
const parsed = await invokeLoopCost(input);
const tokensPerRun = parsed.scenarios?.[scenario]?.tokensPerRun;
if (typeof tokensPerRun !== 'number') {
- throw new Error(`loop-cost output missing scenarios.${scenario}.tokensPerRun.`);
+ const hint = scenario === 'caching'
+ ? ' This pattern may be missing stable_fraction in registry.yaml.'
+ : '';
+ throw new Error(`loop-cost output missing scenarios.${scenario}.tokensPerRun.${hint}`);
}
return tokensPerRun;
}
diff --git a/tools/loop-context/dist/cli.js b/tools/loop-context/dist/cli.js
index 6eada01..676c3f7 100755
--- a/tools/loop-context/dist/cli.js
+++ b/tools/loop-context/dist/cli.js
@@ -150,8 +150,10 @@ Options:
estimate instead of typing a number. Ignored if
--token-budget is also given (explicit wins).
--budget-level <L1|L2|L3> Readiness level for --budget-from-pattern (default: L1)
- --budget-scenario <realistic|action|report>
- Which loop-cost scenario to use (default: realistic)
+ --budget-scenario <realistic|action|report|caching>
+ Which loop-cost scenario to use (default: realistic).
+ caching requires stable_fraction set on the pattern
+ in registry.yaml (see loop-cost --with-caching).
--budget-cadence <spec> Cadence override passed through to loop-cost
--budget-conservative Use the slower cadence in a range (loop-cost flag)
--daily-budget-from-pattern <id>
diff --git a/tools/loop-context/package-lock.json b/tools/loop-context/package-lock.json
index dfbc5d3..765aa6b 100644
--- a/tools/loop-context/package-lock.json
+++ b/tools/loop-context/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@cobusgreyling/loop-context",
- "version": "1.2.0",
+ "version": "1.5.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@cobusgreyling/loop-context",
- "version": "1.2.0",
+ "version": "1.5.0",
"license": "MIT",
"dependencies": {
"@cobusgreyling/loop-cost": "^1.1.0"
diff --git a/tools/loop-context/package.json b/tools/loop-context/package.json
index 3cb4bbb..6e3a667 100644
--- a/tools/loop-context/package.json
+++ b/tools/loop-context/package.json
@@ -1,7 +1,7 @@
{
"name": "@cobusgreyling/loop-context",
- "version": "1.4.0",
- "description": "Stateful memory manager for agent loops — summarize, prune, and inject context, with a circuit breaker that escalates stagnant or no-progress runs instead of burning tokens.",
+ "version": "1.5.0",
+ "description": "Stateful memory manager for agent loops \u2014 summarize, prune, and inject context, with a circuit breaker that escalates stagnant or no-progress runs instead of burning tokens.",
"type": "module",
"main": "dist/context-manager.js",
"exports": {
diff --git a/tools/loop-cost/README.md b/tools/loop-cost/README.md
index 2fa66d0..98079d2 100644
--- a/tools/loop-cost/README.md
+++ b/tools/loop-cost/README.md
@@ -10,6 +10,7 @@ Uses cost metadata from `patterns/registry.yaml`.
npx @cobusgreyling/loop-cost --pattern ci-sweeper --cadence 15m --level L2
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --json
npx @cobusgreyling/loop-cost --list
+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --with-caching
```
**From this repo:**
@@ -30,6 +31,7 @@ npm test
| `--orchestration` | Multi-agent action cost: `single` (default), `maker-checker`, `parallel:N`, `debate:R` |
| `--conservative` | Use slower cadence from ranges |
| `--json` | Machine-readable output |
+| `--with-caching` | Add a **caching** scenario: apply cache-read discount to the stable (cacheable) fraction of report/action tokens from `stable_fraction` in `registry.yaml` |
## Scenarios
@@ -39,6 +41,7 @@ Each estimate includes:
- **Full triage** — every run does a full scan
- **Action every run** — implementer + verifier every time (worst case)
- **Realistic blend** — level-based mix (documented in output)
+- **Caching** (opt-in via `--with-caching`) — discounts the stable portion of tokens using Anthropic-style cache-read pricing (~10% of base input); omitted when a pattern has no `stable_fraction`
Pair with `loop-budget.md` (scaffolded by `loop-init`) and `loop-audit` cost observability checks.
diff --git a/tools/loop-cost/dist/cli.js b/tools/loop-cost/dist/cli.js
index 1d12976..4fb7c40 100755
--- a/tools/loop-cost/dist/cli.js
+++ b/tools/loop-cost/dist/cli.js
@@ -14,6 +14,7 @@ function parseArgs(argv) {
let json = false;
let list = false;
let orchestration = 'single';
+ let withCaching = false;
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (a === '--pattern' || a === '-p')
@@ -30,10 +31,12 @@ function parseArgs(argv) {
json = true;
else if (a === '--list')
list = true;
+ else if (a === '--with-caching')
+ withCaching = true;
else if (a === '--help' || a === '-h')
return { help: true };
}
- return { help: false, pattern, cadence, level, conservative, json, list, orchestration };
+ return { help: false, pattern, cadence, level, conservative, json, list, orchestration, withCaching };
}
async function loadRegistry() {
const candidates = [
@@ -70,6 +73,8 @@ Options:
Multi-agent action cost: single (default),
maker-checker, parallel:N, debate:R
--conservative Use slower cadence from ranges (e.g. 15m not 5m)
+ --with-caching Show estimate with prompt caching applied
+ (requires stable_fraction in the pattern's cost block)
--json Machine-readable output
--list List pattern ids
-h, --help This help
@@ -113,6 +118,7 @@ Examples:
level: args.level,
conservative: args.conservative,
orchestration: args.orchestration,
+ withCaching: args.withCaching,
});
if (args.json)
console.log(JSON.stringify(result, null, 2));
diff --git a/tools/loop-cost/dist/estimator.d.ts b/tools/loop-cost/dist/estimator.d.ts
index 8011c28..db8d38e 100644
--- a/tools/loop-cost/dist/estimator.d.ts
+++ b/tools/loop-cost/dist/estimator.d.ts
@@ -5,6 +5,10 @@ export interface PatternCost {
tokens_noop: number;
tokens_report: number;
tokens_action: number;
+ /** Fraction (0.0-1.0) of report/action tokens that are stable, repeated
+ * content (STATE.md, skills, system prompt) eligible for prompt caching.
+ * Optional — patterns without it are treated as fully variable (0). */
+ stable_fraction?: number;
suggested_daily_cap: number;
early_exit_required: boolean;
}
@@ -42,6 +46,7 @@ export interface EstimateInput {
level: ReadinessLevel;
conservative?: boolean;
orchestration?: string;
+ withCaching?: boolean;
}
export interface EstimateResult {
patternId: string;
@@ -71,6 +76,11 @@ export interface EstimateResult {
tokensPerDay: number;
assumptions: string;
};
+ caching?: {
+ tokensPerRun: number;
+ tokensPerDay: number;
+ savingsPercent: number;
+ };
};
warnings: string[];
}
diff --git a/tools/loop-cost/dist/estimator.js b/tools/loop-cost/dist/estimator.js
index 24809df..8e83acf 100644
--- a/tools/loop-cost/dist/estimator.js
+++ b/tools/loop-cost/dist/estimator.js
@@ -100,6 +100,16 @@ function formatTokens(n) {
return `${Math.round(n / 1_000)}k`;
return String(n);
}
+// Anthropic prompt caching: cache reads bill at roughly 10% of base input
+// token cost. Only the stable portion of a run's tokens (STATE.md, skills,
+// system prompt — unchanged since the last cache write) benefit; the
+// variable portion (fresh scan results, diffs) still costs full price.
+const CACHE_READ_DISCOUNT = 0.1;
+function applyCaching(tokensPerRun, stableFraction) {
+ const stable = tokensPerRun * stableFraction;
+ const variable = tokensPerRun - stable;
+ return Math.round(variable + stable * CACHE_READ_DISCOUNT);
+}
export function estimateCost(input) {
assertValidLevel(input.level);
const cadence = input.cadence ?? input.pattern.cadence;
@@ -117,6 +127,13 @@ export function estimateCost(input) {
cost.tokens_report * mix.report +
actionPerRun * mix.action;
const realisticDay = Math.round(realisticPerRun * runsPerDay);
+ let caching;
+ if (input.withCaching && cost.stable_fraction) {
+ const cachedPerRun = applyCaching(realisticPerRun, cost.stable_fraction);
+ const cachedDay = Math.round(cachedPerRun * runsPerDay);
+ const savingsPercent = Math.round((1 - cachedPerRun / realisticPerRun) * 100);
+ caching = { tokensPerRun: cachedPerRun, tokensPerDay: cachedDay, savingsPercent };
+ }
const warnings = [];
if (cost.early_exit_required) {
warnings.push('Early-exit triage is required — empty watchlist should exit in <5k tokens.');
@@ -152,6 +169,7 @@ export function estimateCost(input) {
tokensPerDay: realisticDay,
assumptions: mix.assumptions,
},
+ caching,
},
warnings,
};
@@ -173,6 +191,9 @@ export function formatEstimateHuman(r) {
lines.push(` Full triage: ${formatTokens(r.scenarios.report.tokensPerDay)} (${formatTokens(r.scenarios.report.tokensPerRun)}/run)`);
lines.push(` Action every run: ${formatTokens(r.scenarios.action.tokensPerDay)} (${formatTokens(r.scenarios.action.tokensPerRun)}/run)`);
lines.push(` Realistic blend: ${formatTokens(r.scenarios.realistic.tokensPerDay)} (${r.scenarios.realistic.assumptions})`);
+ if (r.scenarios.caching) {
+ lines.push(` With prompt caching: ${formatTokens(r.scenarios.caching.tokensPerDay)} (${r.scenarios.caching.savingsPercent}% reduction vs. realistic blend)`);
+ }
if (r.warnings.length) {
lines.push('');
lines.push('Warnings:');
diff --git a/tools/loop-cost/package-lock.json b/tools/loop-cost/package-lock.json
index 7cc7ecc..57c1404 100644
--- a/tools/loop-cost/package-lock.json
+++ b/tools/loop-cost/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@cobusgreyling/loop-cost",
- "version": "1.0.0",
+ "version": "1.2.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@cobusgreyling/loop-cost",
- "version": "1.0.0",
+ "version": "1.2.0",
"license": "MIT",
"dependencies": {
"yaml": "^2.8.0"
diff --git a/tools/loop-cost/package.json b/tools/loop-cost/package.json
index a804d99..3f1f010 100644
--- a/tools/loop-cost/package.json
+++ b/tools/loop-cost/package.json
@@ -1,6 +1,6 @@
{
"name": "@cobusgreyling/loop-cost",
- "version": "1.1.0",
+ "version": "1.2.0",
"description": "Estimate token budgets and daily costs for loop engineering patterns. By cadence, readiness level (L1/L2/L3), and coding agent tool.",
"type": "module",
"bin": {
@@ -53,4 +53,4 @@
"@types/node": "^20.0.0",
"typescript": "^5.0.0"
}
-}
\ No newline at end of file
+}
diff --git a/tools/loop-cost/registry.json b/tools/loop-cost/registry.json
index f46ece9..bb1a704 100644
--- a/tools/loop-cost/registry.json
+++ b/tools/loop-cost/registry.json
@@ -41,6 +41,7 @@
"tokens_noop": 3000,
"tokens_report": 80000,
"tokens_action": 250000,
+ "stable_fraction": 0.35,
"suggested_daily_cap": 2000000,
"early_exit_required": true
}
@@ -81,6 +82,7 @@
"tokens_noop": 5000,
"tokens_report": 50000,
"tokens_action": 200000,
+ "stable_fraction": 0.35,
"suggested_daily_cap": 100000,
"early_exit_required": false
}
@@ -124,6 +126,7 @@
"tokens_noop": 5000,
"tokens_report": 50000,
"tokens_action": 200000,
+ "stable_fraction": 0.35,
"suggested_daily_cap": 1000000,
"early_exit_required": true
}
@@ -166,6 +169,7 @@
"tokens_noop": 5000,
"tokens_report": 40000,
"tokens_action": 150000,
+ "stable_fraction": 0.35,
"suggested_daily_cap": 200000,
"early_exit_required": false
}
@@ -211,6 +215,7 @@
"tokens_noop": 5000,
"tokens_report": 60000,
"tokens_action": 300000,
+ "stable_fraction": 0.35,
"suggested_daily_cap": 500000,
"early_exit_required": true
}
@@ -256,6 +261,7 @@
"tokens_noop": 5000,
"tokens_report": 35000,
"tokens_action": 80000,
+ "stable_fraction": 0.35,
"suggested_daily_cap": 100000,
"early_exit_required": false
}
@@ -300,6 +306,7 @@
"tokens_noop": 3000,
"tokens_report": 30000,
"tokens_action": 60000,
+ "stable_fraction": 0.35,
"suggested_daily_cap": 80000,
"early_exit_required": false
}