feat: close out cost docs, cache-write accounting, context steering, fork, per-session cwd #26
No reviewers
Labels
No labels
code-review
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
sam/brainless!26
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/cost-docs-write-context-fork-cwd"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Five small items closing the cost-awareness and session-lifecycle loops. Build, vet, full test suite, golangci-lint (0 issues), and the pure-Go racedetector are all green on the branch head.
1. Document the cost feature in the README
The
pricing/budgets/historyblocks shipped with zero user docs. Added a "Cost awareness" section covering prices (per-model, per-million, currency label, free-by-absence), the model-facing clock cost line, budgets (opt-in, priced models only), measured history, and the newcontextWindow. Also refreshed the stale "Next steps" (session capabilities have been advertised since #25; fork and per-session cwd are done here) and the "what's consciously missing" bullet, and updatedbrainless.json.example+ the Gemma wiring section.2. Cache-write token accounting (cost_plan.md's explicit "add when")
ADK's
convertUsageparsescache_write_tokensand discards it beforegenaisees it, andgenaihas no field for it. Instead of forking the whole ADK module for two lines, a middleware on each registry client (openai-gooption.WithMiddleware) reads the count from the raw response body into a per-entry box before ADK decodes it; the selector (and the compactioncostingLLM) folds it into the round.usageCostgains the third term: writes are uncached input billed atcacheWritePerMillion, which defaults to the fresh input rate (OpenAI's convention, so the default is a no-op). The operator log gainscache_write_tokens. Persisted events still lose the count, so a restart's seeded session total prices writes at the input rate — documented incost_plan.md, which is updated to mark the non-goal resolved.3. Context-size steering for free local models
contextWindowon a model (tokens) makes a free model's clock block showcontext: 31k / 128k tokensinstead of a money line — the natural home the plan parked. The local Gemma example in the README andbrainless.json.examplenow declarecontextWindow: 4096.4. session/fork
UnstableForkSession(the ACP experimental method): the fork gets a fresh id, a verbatim copy of the source conversation's events (ids, timestamps, state deltas intact), its own persisted cwd, becomes the active session, and connects the requested MCP servers. Advertised viasessionCapabilities.forkininitialize.5. Per-session cwd
NewSessionnow creates the session row up front with the working directory in the session state (brainless.cwdkey), sosession/listreports each session's own cwd — Paseo feeds it back intosession/loadand its import UI — across restarts.session/load/resumeset the dir from the request, and a restart-resumed prompt restores the session's own cwd for the file tools. Sessions created but never prompted now appear in the list (they exist in the store; that is whatsession/listmeans); sessions recorded before this feature fall back to the most recent dir.Tests added
usageCostcache-write cases (billed at the write rate, default-to-input no-op, clamped out of a fully cached prompt, free ignores writes)cacheWritePerMillion/write-rate-default config validationreadCacheWriteTokensshapes + end-to-end through a real registry client)Reviewed at head
e912043(feat/cost-docs-write-context-fork-cwd) with the full toolchain, not from memory. Verified in this session:go build ./...,go vet ./...,go test ./...(all packages),racedetector test ./...(pure-Go race detector, no data races),golangci-lint run(0 issues),govulncheck(0 reachable vulnerabilities; no go.mod/go.sum changes and noreplacedirectives in the PR).Substantive checks that came back clean:
cacheWriteMiddlewaresignature matches openai-go v3.71.1option.WithMiddleware(func(*http.Request, option.MiddlewareNext) (*http.Response, error))(option/requestoption.go:102). The middleware runs inside the retry loop, so the box ends up holding the last attempt's count — the attempt whose response is decoded — andtake()drains it before the next call, so stale counts cannot be billed. Calls are serialized byturnMu(Prompt holds it for the whole turn;startMCPtakes it internally; compaction runs synchronously inside the runner), so the shared box between the session client and the summarizer is safe.UnstableMcpServer↔McpServerand the config-option variants serialize to identical JSON (verified against acp-go-sdk v0.13.5 types_gen.go: sametypediscriminator, same field names), so the marshal/unmarshal round trips are faithful. The SDK validatesCwdserver-side before dispatch, andSessionForkCapabilitiesexists.usageCostwrite handling is correct for the OpenAI convention (write tokens inside the uncached input; default write rate = input rate makes the subtraction a no-op), nil/free pricing short-circuits beforeCacheWriteRate(), and the arithmetic is pinned by the new table cases including the fully-cached clamp.tools.Diris RWMutex-protected;writeTokensBoxisatomic.Int64; no goroutines added. The e2e suite (per-session cwd across restart, fork copy/replay, write-premium budget cancellation) runs green, including under the race detector.Three non-blocking suggestions are inline (🟡). No blocking findings — approving.
@ -636,1 +688,4 @@// working directory, so relative file paths resolve where the session// was created.if h.clock != nil {h.ensureSessionCwd(ctx, sid)🟡 SUGGESTION —
ensureSessionCwdruns on every prompt, not only for sessions this process never opened. Its doc comment says it restores the cwd "when a prompt arrives on a session this process never opened with a lifecycle call", but the call at harness.go:691 is unconditional underh.clock != nil: even after NewSession/LoadSession/ResumeSession seth.dirfrom the client's request, the next Prompt silently overwrites it with the persisted creation cwd. A client that loads a session with a different cwd (e.g. the workspace moved) is reverted at prompt time, and every prompt pays an extrastore.Get. Concrete fix: remember the session ids this process already opened via a lifecycle call and skip the restore for them (or only restore when the process is resuming a session it never opened).@ -272,0 +341,4 @@// usage.prompt_tokens_details.////nolint:ireturn // openai-go's option type is an interface by designfunc cacheWriteMiddleware(box *writeTokensBox) option.RequestOption {🟡 SUGGESTION — the capture only works for non-streaming responses, and the constraint is undocumented.
io.ReadAll(res.Body)on an SSE stream blocks until the stream ends (defeating incremental delivery), andreadCacheWriteTokenscannot parse a multi-object SSE body (json.Unmarshalof the whole blob fails → 0), so cache-write tokens are silently unbilled on a streamed call. Not reachable today — the runner pinsagent.StreamingModeNone(harness.go:711) and ADK only streams whenrc.StreamingMode == agent.StreamingModeSSE(adk/v2 base_flow.go:975), souseStreamis always false — but the middleware is installed unconditionally on every registry client. Consider a one-line doc note (or a guard) so a future streaming path does not quietly lose the count.@ -506,3 +545,1 @@// - money = (uncachedInput*input + cachedInput*cachedInput + output*output)// / 1e6, where an omitted cachedInputPerMillion defaults to the fresh// input rate (no cache discount assumed; the conservative direction).// - money = (uncachedInput*input + cachedInput*cachedInput + write*writeRate🟡 SUGGESTION — the wrapped formula reads as subtraction. The continuation line starts with the list marker
-, somoney = (… + write*writeRate/- output*output) / 1e6visually reads aswrite*writeRate − output*output, and the+before the output term is missing (verified in the head file, lines 545-546). Fix: put the whole formula on one line, e.g.money = (uncachedInput*input + cachedInput*cachedInput + write*writeRate + output*output) / 1e6, or indent the continuation so the bullet marker is not inside the expression.All three 🟡 findings from review 51 are addressed at head
4db61b8(fix: address review findings (doc formula, cwd restore gate, streaming note)):+ output*outputon an indented line, so it no longer renders as a nested list item (write*writeRate − output).openedset (guarded byh.mu), andrestoreSessionCwdonly restores for sessions never opened: a client that loads a session with a different cwd (moved workspace) keeps it, and opened sessions no longer pay astore.Getper prompt. NewTestRestoreSessionCwdpins both halves.agent.StreamingModeNone.Verified at the new head:
go build,go vet,go test ./...,golangci-lint run(0 issues),racedetector test ./internal/harness/(no data races).