[vraspar]

What

C2 of the router contract and fee plan: the background top-up, and PR 4 of the hook-leg latency plan. A prompt never carries the routing deposit.

Based on main, now that #532 and #534 are merged. Merge after the server change that adds the warm form is deployed. The server's CI reads this repo's main fixtures, so merging earlier turns it red on the warm fixtures.

• The top-up. tenjin mcp deposits with one background warm call to the paid route, which settles at $0 and carries the deposit. It runs through the payer's normal turns, ledger and detach logic, with its own 15 s budget. It triggers:
  • on start, when the channel can't cover a fee (a new channel included);
  • right after a paid call leaves the channel below one quoted fee;
  • when a call's SDK still asks for a deposit, which is refused and starts the top-up instead.
• Waiting. A call that meets a top-up in flight waits until 1 s before its deadline, then pays from the channel. Running out of time is topping_up: no fault, no notice. A topping-up memo naming the wallet stops a second process from depositing at the same time.
• Sizing, which reached main with feat(router): pay the router's quoted fee, capped at $0.003, and route only on the paid route #534; this PR keeps it and has the wallet_low notice name the balance. The smallest of extra.minDeposit (read with the SDK's parseAnnouncedMinDeposit, falling back to $0.05), the wallet and the per-call limit.
  • Never below 10 quoted fees or what the next voucher needs, and never above the SDK's $0.25 cap. The daily budget stays with the authorizer.
  • Below that floor it is wallet_low, and the once-per-session notice names the balance.
  • The balance is read only inside the top-up, never on a prompt.
• Either side can ship first. An answer other than the warm shape (an older server's 400 settles nothing) writes a warm-absent memo per machine and router origin. For an hour, deposits ride the next paid call as today. A 429 or 5xx backs off instead.
• Backoff on a refused top-up:
  • wallet_low retries every 2 minutes at most (30 s, then 2 min), so someone who funds mid-session routes again within 2 minutes.
  • Other refusals back off 30 s, then 2 min, then 10 min.
• Copy. The install question says "…from funds set aside (the router's suggested amount, up to $0.25 at a time) and names your wallet address…", at the base's 371 characters.
• Fixtures. The warm exchange and a tolerant exchange (honored, plus a spec with requires) are added. The fixtures README says the server keeps a copy refreshed from this one until its CI reads them from this repo's main.

Not in this PR

• Idle-channel refunds. They wait until CDP's facilitator supports delegated refunds.
• Changing the quote to $0.001. That is a server one-liner once old CLIs leave paid traffic.

Checks

• Typecheck, eslint and repo-wide prettier pass.
• vitest run on 22 covering files (1,172 tests) on the main change, then 8 files (719 tests) on the backoff follow-up. That includes both suite-wide consistency tests and dist-chunks.
• The fake router answers warm the way the server change does, and also with a 400 like an older server.
• After review and the merge of feat(router): pay the router's quoted fee, capped at $0.003, and route only on the paid route #534's fixes (530695b): typecheck, eslint and prettier pass, and vitest run passes on 18 files (1,201 tests).
• End to end against a local router with the warm form and the fee off, using a copy of a real wallet:
  • With $0.097 set aside, tenjin mcp starts without a top-up.
  • With no channel, one background warm goes out about 0.6 s after start, gets 200 and is read as done, with no payment and no warm-absent memo. A lookup in the same process routes.
  • With no wallet, the offer is held back locally (no_wallet).
  • Not exercised: the deposit itself and the warm fallback against an older server, which need the fee on.
• After merging main (e8e8a8b): typecheck and eslint pass, and vitest run passes on 12 files (854 tests), both suite-wide consistency tests included.
• The exit-wait fix (9c6cdc7): typecheck, eslint and prettier pass, and vitest run passes on 3 files (338 tests), the skills-text consistency test included.
• No pack-smoke run locally.

Notes for reviewer

• The plan had a money refusal wait for the next process. This uses a timed backoff instead, so funding a wallet doesn't need a restart.
• The request tool also leaves its deposit to the top-up, per the plan's "only a warm call deposits".

🤖 Generated with Claude Code

Confidence Score: 5/5

The changes since the previous review appear safe to merge; the shutdown wait now covers both payment windows.

Summary

The PR moves routing deposits onto background warm calls, with an older-router fallback.

• Routing deposits move to background top-ups instead of prompt calls.
• Router fixtures now pin the warm and tolerant request exchanges.

_{Reviews (8) · Last reviewed commit: "fix(router): wait out a detached top-up ..." · Reviewed by Greptile}

[aether-agent]

_{🤖 Reviewer · Review PR #533: feat(router): top up the routing channel in the background; a pr… · claude-code · claude-opus-5-5}

Deep review at dcfde56 (merge base fce1cc2). Process:

• A context pack, then 13 auditors (12 plus one catch-up round). The ledgers cover every changed and context line of the 123 hunks, and no line was left unaudited.
• 6 file owners and 6 independent reviewers.
• eslint and semgrep (p/default, p/security-audit) on the changed files were clean, so there were no analyzer leads.

The core design holds up:

• The top-up goes through the same turn queue, ledger commit and authorizer as every other call.
• A waiting call never holds the turn, so nothing deadlocks.
• Carrier and inline deposits get the same wallet_low check, policy check and authorizer. A router cannot push a deposit past the per-call or daily limits or the $0.25 cap.
• Typecheck is clean at this head (recorded).

Three p2s:

• Nothing waits for the background deposit at shutdown.
• A warm deposit that outlives its 15 s budget is never announced.
• The backoff counter carries over across refusal reasons, so a transient failure right after funding can hold routing off for 10 minutes.

The nits are mostly that cluster's edges: the cross-process memo, transient refusals told as payment_failed, a channel-credit read that can see the wrong channel, the warm fixture not matching what the client sends, and docs that still describe the old inline deposit.

Recorded test run: npx vitest run on the 9 covering router test files failed 1 of 363. routing-payer.test.ts "reserves the last daily deposit only once when two wallets race" got ['budget_reached', 'deposit_deferred']. It passed 6 of 6 when run alone, so it is timing dependent under load. A silent deposit_deferred there means one wallet's call ended neither paid nor refused as expected.

Test gaps (not posted inline):

• hooks-fee.test.ts:611 and routing-payer.test.ts:717 wait out a wallet_low backoff with TOP_UP_BACKOFF_MS[0] instead of WALLET_LOW_BACKOFF_MS[0]. They pass only while both are 30 s.
• fee.test.ts:53 and routing-payer.test.ts:223-237 cannot see the SDK ceiling: the default per-call limit already equals MAX_CHANNEL_DEPOSIT_ATOMIC, so removing least(amount, o.maxAtomic) stays green.
• routing-payer.test.ts:270 ("tops up once every ten") no longer pins the interval. The deposits === 1 check after nine calls was removed.
• routing-payer.test.ts:710-715 says "no second balance read" but never counts walletBalance calls.
• The removed limit_below_deposit test's check that the ledger stays at 0 (old :550) has no replacement.
• Neither mcp.test.ts:1166-1177 nor the routing-payer.test.ts afterEach awaits payer.idle() before rm(dir), so the background top-up can race the temp-dir teardown.
• The router-off case at mcp.test.ts:1182 can pass vacuously: topUpAtStart isn't tracked by idle(), so a 200 ms sleep is the only guard.
• The money check at wire.test.ts:379-395 omits wire-tool-request-by-id-tolerant.json.
• spend-question.test.ts:14's stated reason ("a funded wallet deposits $0.25") is stale.

Single-source and unverified (not posted inline):

• mcp.ts:463-466: on a machine with both a plugin and a settings install, each tenjin mcp tops up at start. Only its own routes can announce the deposit, so the settings server's deposit may never be said.
• routing-payer.ts:348-350: done assumes the server's warm 402 quotes at least the routing fee. If it quotes less, the SDK sends no deposit, the backoff resets, and every prompt defers and sends warm again.

Refuted: a failed warm-absent memo write leaving an older router stuck. writeRouterMemo swallows the error, but the same unwritable data dir fails commitDeposit (routing-payer.ts:884) before any deposit is sent.

Smaller doc staleness, listed rather than posted:

• docs/agent-permissions.md:25: the reason given for the $0.25 per-call floor.
• decision.ts:830-832: the fee doc ("this route's calls") versus the ?? this.quoted fallback.
• The Call.deposit doc at routing-payer.ts:323-324, for a deferred call.
• fixtures/README.md:422-423: the "diagnostics on every non-execute answer" rule, which wire-warm.json breaks.
• fixtures/README.md:376-378: the file table, which predates this PR.
• fee-test-utils.ts:60-64 and :116-118: the warms and log docs.

No lines were left unaudited.

[aether-agent]

_{🤖 Reviewer · Review PR #533: feat(router): top up the routing channel in the background; a pr… · claude-code · claude-opus-5-5}

Re-review at 69d0d2c. Since 2a8eacc the only change is a renamed test in src/router/fee.test.ts, and the new name says what the test checks: it pins CHANNEL_DEPOSIT_ATOMIC to the router's announced $0.05 hint. My last review was at 530695b, so I also read the merges in between.

Changes since 530695b:

• $0.05 hint: the hint is now $0.05 (50000 atomic), and FakeRouter announces it by default.
• Floor: doctor (canPayRouting) and the wallet_low text now use the payer's floor, DEPOSIT_FLOOR_FEES × ROUTING_FEE_CEILING_ATOMIC ($0.03), not the hint. A wallet between the floor and the hint is no longer refused offline while the payer would route it. The payer's floor is 10 × the quote, and the quote is at or below the ceiling, so doctor never passes a wallet the payer would refuse. This resolves my earlier nit about doctor sizing with the fixed hint.

Still open, not blocking: src/router/mcp.ts:622. drained() waits only TOP_UP_TIMEOUT_MS, but a top-up's deposit can run longer on its detached tail, so the wait should be TOP_UP_TIMEOUT_MS + DETACHED_CEILING_MS. The topping-up memo gaps, the channelCredit max and the zero-quote floor are unchanged since my earlier reviews.

Checks I ran at this head:

• Typecheck: passes.
• Tests: the 7 router test files this delta touches ran 352 tests, and all passed.

No new findings.

[A1igator]

Re-review at 69d0d2c: 1 of 1 closed

Round 4, layer over #534 at 3cc1893. Delta since round 3 (530695b): two merges of #534's $0.05 hint, 56962e0 (doctor's floor), and the two changeset notes.

Open

None.

New

Should fix

1. On the common low-wallet path the once-per-session wallet_low line names no balance, while docs/agent-permissions.md says the next call names it. tenjin mcp tops up at start (

   tenjin-agent/src/router/mcp.ts

   Line 665 in 69d0d2c

   if (atStart === true) void topUpAtStart(ctx, payer, rest.handlerDeps?.cwd ?? process.cwd());

   ), a wallet under ten fees is refused there with its balance, and the first prompt inside the 30-second WALLET_LOW_BACKOFF_MS window reaches deferral, which drops balanceAtomic and depositAtomic before refuse (

   tenjin-agent/src/router/routing-payer.ts

   Lines 920 to 929 in 69d0d2c

   	private deferral(call: Call): never {
   	const failed = this.backedOff();
   	if (failed !== null) {
   	// A refusal said again: not the balance it read, which may be old now.
   	call.facts = failed.quotedAtomic !== undefined ? { quotedAtomic: failed.quotedAtomic } : {};
   	this.refuse(failed.why);
   	}
   	void this.topUp(call.router, this.channel!.payer);
   	this.refuse(DEPOSIT_DEFERRED);
   	}

   ), so the session's one line is the static $0.03 sentence and the later refusal that re-reads the balance is the same reason, no longer news. Either carry failed.facts() on a backed-off refusal (that read is at most 30 seconds old) or drop "naming the balance" from the doc sentence (

   tenjin-agent/docs/agent-permissions.md

   Line 45 in 69d0d2c

   - The routing fee is paid only by `tenjin mcp`, with the stock x402 client, only to the configured router's paid route, and only in USDC on Base over `batch-settlement`. It pays what that route's 402 quotes when the quote is at or below the ceiling this CLI ships, $0.003, the fee every install so far agreed to; a quote above it is not paid, and the call tells you so once, with the price quoted. Nothing else about the router is pinned, not its payee and not an exact price: the bounds are its origin, that ceiling and the limits below. A provider's 402 never meets this ceiling: a tool's payment is held to its own spec's price. The wallet has one routing channel, and no routing call carries its deposit. When the channel cannot cover the next fee, `tenjin mcp` tops it up in the background: one `warm` request to the same paid route, which the server answers without routing and charges nothing for, carries the deposit. It does this when it starts, after a paid call leaves the channel unable to cover the next fee, and when a call finds it so; a call that meets a top-up in progress waits for it inside its own time limit, then pays from the channel. The deposit is the smallest of the server's hint (its 402's `extra.minDeposit`, currently $0.05), the wallet balance and `maxAutoSpend`, never less than ten quoted fees and never more than the stock SDK's $0.25 ceiling. A wallet holding more than the hint keeps the rest, which pays for the tools routing suggests; the routing channel cannot. A wallet between ten fees and the hint deposits what it holds. A wallet below ten fees is refused as too low, and the next call says so once, naming the balance; when the balance cannot be read, the deposit is the hint. While the router has the `warm` form, the balance is read for the top-up alone, never on a prompt. A top-up refused for a low wallet waits 30 seconds before the next, then 2 minutes at most; any other refusal waits 30 seconds, then 2 minutes, then 10. A router whose answer to `warm` is a 2xx without the `warm` answer, or a 3xx or 4xx other than a 402 or 429 (an older server answers 400), has no form: for an hour after, the deposit rides the next paid call, as it did before the form, and that call reads the balance. Unused funds remain yours. A deposit is an automatic payment: it is reserved in `spend.json` before it is signed, so it must fit `maxAutoSpend`, the day's `sessionBudget` and `allowlistCreators` (the router's host is the creator), and it is counted from the moment it is sent, so a lost answer or a killed process leaves it counted; only an answered 4xx or 5xx, on which the server settles nothing, gives it back. The deposit counts against the spending limits: the fees come out of it and are not counted again, so the day's running total never refuses one. Each fee still gets the per-payment checks, at the amount quoted: it has to fit `maxAutoSpend` (a 0 an earlier release let you set refuses it) and pass `allowlistCreators`, and a `sessionBudget` of 0 refuses it. A fee that fails one is not paid, even from a channel that is already funded, and the call is skipped. The server may charge less than it quoted, and the channel records the lower charge. Approving the limits at install, where the question names the fee, is what approves it.

   ).

Closed as decisions

• channelCredit is the largest credit across every channel file (round 1, item 2): declined for now as the owner's call; the check moves to the channel the 402 names when a wallet switch is planned. Settled, not re-argued.
• The top-up reads the wallet balance over RPC and sizes the deposit from it (round 1, item 3): settled by the operator; the rebase against #523 decides it.

Facts, not findings: doctor and the payer agree on the wallet_low floor, ten fees, $0.03 at the $0.003 ceiling (canPayRouting with DEPOSIT_FLOOR_FEES * ROUTING_FEE_CEILING_ATOMIC, the payer with ten times the quote, equal while the router quotes the ceiling), and a wallet between the floor and the $0.05 hint deposits what it holds on both. The top-up sizes from the 402's extra.minDeposit with CHANNEL_DEPOSIT_ATOMIC as the no-hint fallback only; the fixtures README's extra.minDeposit 50000 matches the server. No balance read is added beyond the one the top-up makes. Locally at 69d0d2c: tsc --noEmit and vitest on the twelve touched test files (637 tests) pass.

[vraspar]

@A1igator re your round 4 at 69d0d2c:

• Should fix 1, the repeated wallet_low line names no balance: fixed on the doc side, in 33ae023. Carrying failed.facts() would put a stale balance in front of someone who funds the wallet inside the backoff. routing-payer.test.ts › "holds the next top-up off after a refusal…" pins that case: funded to $10, the repeated refusal must not show the earlier $0. docs/agent-permissions.md and the release note now promise the balance only when that call read it.

🤖 Generated with Claude Code

[aether-agent]

_{🤖 Reviewer · Review PR #533: feat(router): top up the routing channel in the background; a pr… · claude-code · claude-opus-5-5}

Re-review at 33ae023. This commit changes only docs: .changeset/background-top-up.md and docs/agent-permissions.md. No source file changed since 69d0d2c.

The new wording says a repeated wallet_low names no balance, and it matches the code:

• When a refused top-up is still holding off the next one, RoutingPayer.deferral (src/router/routing-payer.ts:919-925) gives the call only quotedAtomic. The balance the earlier top-up read is dropped, because it may be older than a fund.
• A call that waited on a fresh top-up's refusal gets that top-up's facts (:518), so its message can still name the balance just read.
• unpaidSentence (src/router/fee.ts:232) names the balance only when both balanceAtomic and depositAtomic are present.

Earlier findings:

• Unchanged nit: src/router/mcp.ts:622. drained() waits only TOP_UP_TIMEOUT_MS, not TOP_UP_TIMEOUT_MS + DETACHED_CEILING_MS. The other earlier nits are also unchanged.
• Blocking: none.

Checks: I ran nothing new. The source is identical to 69d0d2c, where typecheck passed and 352 router tests passed.

[A1igator]

Re-review at 33ae023: nothing left I would block on.

Round 5, layer over #534 at 3cc1893. Delta since round 4 (69d0d2c): one docs commit, no source change. Round 4's should fix (the repeated wallet_low line names no balance) is closed on the doc side: docs/agent-permissions.md and the release note now promise the balance only on the call that read it, which is what deferral does (a backed-off refusal repeats the reason without the earlier read), and routing-payer.test.ts "holds the next top-up off after a refusal" pins the case the author names: funded to $10 inside the backoff, the repeat carries no balance. Carried as decisions, not re-argued: channelCredit taking the largest credit across channel files (owner declined for now), and the top-up's RPC balance read (settled by the rebase against #523). Locally at 33ae023: vitest on routing-payer and fee tests (113 tests) passes.

bot reivew

[aether-agent]

_{🤖 Reviewer · Review PR #533: feat(router): top up the routing channel in the background; a pr… · claude-code · claude-opus-5-5}

Re-review at e8e8a8b. The PR now targets main. This delta is two merges: the fee PR's final head (#534) and main, which brings #532 and the hash-wasm wallet unlock (#521).

Merge resolution: correct. No router source file changed since 33ae023, so this PR's $0.05 hint, its deposit sizing and its top-up logic are intact. The only router changes are two test assertions from #534's final head:

• fee.test.ts adds a $0.50-wallet case. It sizes to the hint, as routingDepositAtomic takes the smallest of hint, wallet and per-call limit.
• routing-payer.test.ts checks that only the first deposit was counted in spend.json.

The docs/agent-permissions.md change is #521's unlock wording alone; this PR's routing text is untouched. The files under src/lib/wallet/, the packaging scripts and NOTICE.md come straight from main, and I didn't re-review them.

Earlier findings:

• Unchanged nit: src/router/mcp.ts:622. drained() waits only TOP_UP_TIMEOUT_MS, not TOP_UP_TIMEOUT_MS + DETACHED_CEILING_MS. The other earlier nits are also unchanged.
• Blocking: none.

Checks at this head:

• First run: typecheck and the keystore tests failed because hash-wasm, the new dependency, wasn't installed in this workspace.
• After pnpm install --frozen-lockfile: typecheck passes, and fee, routing-payer and keystore-kdf ran 144 tests, all passing. Both runs are recorded.

[A1igator]

Heads-up from the review loop at e8e8a8b: this PR waits on one author-side action. The Greptile P1 thread on src/router/mcp.ts ("Shutdown loses the deposit answer") is still open. Reply to it or fix it, then resolve it. Nothing else is awaited from the reviewer side right now.

[A1igator]

@vraspar the deposit size is settled: $0.05 (extra.minDeposit 50000) stands as the router's announced minimum, per the owner's call above. The earlier $0.25 figure is withdrawn. Nothing changes in this PR or in tenjin#1055 for it. The one item still on your side here is the open Greptile thread on src/router/mcp.ts.

[aether-agent]

_{🤖 Reviewer · Review PR #533: feat(router): top up the routing channel in the background; a pr… · claude-code · claude-opus-5-5}

Re-review at 9c6cdc7. This commit fixes my open nit at src/router/mcp.ts:622.

drained() now races payer.idle() against TOP_UP_TIMEOUT_MS + DETACHED_CEILING_MS (30 s), not TOP_UP_TIMEOUT_MS alone (src/router/mcp.ts:624):

• Late deposit: a top-up that times out at its 15 s budget can leave its deposit running for up to another 15 s. That deposit now lands, and is recorded in the SDK's channel file, before the process exits.
• Normal shutdown: a shutdown with no top-up in flight still exits as soon as idle() resolves, and the timer is cleared.
• Docs: the changeset and docs/agent-permissions.md change "15 seconds" to "30 seconds", which matches the new bound.

Earlier findings: the other earlier nits are unchanged and none block.

Checks at this head: typecheck passes, and mcp and routing-payer ran 122 tests, all passing.

[A1igator]

Re-review at 9c6cdc7: nothing left I would block on.

[A1igator]

@vraspar review at 9c6cdc7 is clean and CI is green, so the approval waits on one thing from your side: run the background deposit path once on your local machine against tenjin#1055 (approved at 05a9a13), the top-up, the deposit-after-budget notice and the mcp exit wait, and say here that it held. The approval follows that note.

[A1igator]

@vraspar heads-up from the review loop at 9c6cdc7: this PR now conflicts with main after the latest merge there, so it needs a re-merge or rebase before it can land. The other awaited item stands: the local run against tenjin#1055 (top-up, deposit-after-budget notice, mcp exit wait). Both from your side; nothing else is awaited from the reviewer.