fak capability map: spend fewer tokens and turns

fak’s current product focus is agent efficiency: keep stable prompt work reusable, avoid unnecessary model round trips, route each call to an appropriate model, and let operators control long-running sessions without injecting another conversational turn. The security floor remains shipped and indexed, but it is a supporting property of the same tool-call boundary rather than the lead story here.

This page is the short, outcome-first index. It is also queryable: from a source checkout, fak-dev capabilities "token savings" or fak-dev capabilities "turn control" returns machine-readable capability cards with an exact next command and evidence seam. For the complete research and design inventory, use the innovations index; for the full documentation catalog, use docs/index.md.

Start with the largest avoidable cost: extra turns

A model turn costs more than its visible answer. It can resend a long resident prefix, incur provider latency, and create yet more context for every later turn. fak therefore measures and removes turn tax, not only individual token strings.

| Capability | What it changes | Try or inspect it | |—|—|—| | Turn-tax meter | Attributes avoidable round trips to forced policy retry, deterministic tool work, duplicate/replay work, and other turn kinds. | go run ./cmd/turntaxdemo -selfcheck; turn-tax measurement | | Fused deterministic work | Completes kernel-known work at the tool boundary instead of paying for another model turn. | fused-turn architecture |

Live turn control Budgets turns/tokens/context and pauses, resumes, throttles, steers, or stops a served session out of band—without spending a prompt turn to ask the model to control itself. fak help session; operator control plane
Provider clear/new boundary Starts a fresh fak trace when a wrapped provider explicitly clears its conversation, while carrying cumulative limits so the UI command cannot reset quotas. provider clear/new contract
Same-trace ablation Replays one frozen trace with cache levers on/off so savings are attributable rather than anecdotal. fak help ablate; fak ablate --help

The browserless turn-tax demo is the smallest captured spine: its self-check drives the real turnbench path and includes an anti-inflation control where a happy path must report zero saved turns. The shipped fixture currently witnesses 9 avoided turns (5 forced-turn + 4 elision) in its synthetic airline scenario; that is a reproducible fixture result, not a universal workload claim.

Reuse prompt work instead of repaying for it

Capability What it changes Try or inspect it
Stable-prefix reuse (vDSO) Keeps shared setup/provider-cache-compatible prefixes reusable across turns. vDSO cache quickstart
Managed context (ctxmmu) Sheds stale turns while preserving a stable prefix and the information needed to continue. managed context
Tool-output compression Compresses large tool results before they consume model-window tokens; benchmark the built-in corpus or your own captured outputs. fak headroom bench --json; fak headroom bench --dir <captures> --json; live witness
Resume pricing Prices full replay versus cut/reset after cache TTL expiry instead of blindly replaying a large session. fak resume plan --resident-tokens 250000 --idle-seconds 7200 --json
Portable session state Persists, moves, and demand-pages a long-running session instead of forcing a restart or full transcript replay. fak snapshot demo; fak snapshot query --file <image.faksession> --query <question>; session image
Cache-value accounting Reports reused tokens, effective cost, and attributable savings in operator terms. fak info --once; cache-value rollup

Spend expensive inference only where it helps

| Capability | What it changes | Try or inspect it | |—|—|—| | Per-call model routing | Routes calls by task/turn requirements rather than pinning a whole session to one expensive model. | model routing; fak model --help | | Model ladder and acceptance | Separates candidate selection from measured acceptance so a cheaper route is not called a win merely because it is cheaper. | model operations |

Token/cache observability Makes savings visible during operation and audits which default savers have captured effect witnesses instead of counting configured/ready as wins. fak info --once; fak token-defaults-scorecard --effectiveness; token-saving observability

Supporting floor: keep optimization bounded

The same checkpoint also enforces a default-deny capability floor and records decisions. That matters because a faster or cheaper agent that can silently widen its authority is not a net-true improvement. Security details remain fully discoverable in the security and policy guide, but new readers should begin with the efficiency paths above.

Where to go next