Phase 5: agents completion runtime knobs + cache invalidate#1
Merged
cmarguta-alg merged 1 commit intolab_week_3from May 6, 2026
Merged
Phase 5: agents completion runtime knobs + cache invalidate#1cmarguta-alg merged 1 commit intolab_week_3from
cmarguta-alg merged 1 commit intolab_week_3from
Conversation
Closes the four completion query-param gaps and the cache-invalidate
endpoint flagged by the parity audit. Smallest delta of the planned
phases — chosen to land first because it validates the per-phase-PR
rhythm without introducing brand-new architectural surface.
What's in:
- `agents try` and `agents run` learn `--no-cache`, `--no-memory`,
`--no-analytics`, and `--secure-user-token <jwt>`. Maps onto the
backend's documented completion query params and the
X-Algolia-Secure-User-Token header.
- New `agents cache invalidate <agent-id> [--before YYYY-MM-DD]`
wraps `DELETE /1/agents/{id}/cache`. Mirrors `agents delete`'s
confirmation contract: TTY prompts, non-TTY refuses without
`--confirm`, `--dry-run` bypasses both since it's non-destructive.
Polarity calls (worth knowing for future contributors):
- The CompletionOptions.No* fields are inverted from the wire on
purpose. Backend defaults all three to true; only the negative is
interesting to expose at the CLI surface, and `memory=true` would
actually 422 (the schema is `anyOf [{const false}, {type null}]`).
So the wire form omits the param when the No* field is false and
sends `<param>=false` when true. Polarity is pinned end-to-end by
a table-driven wire-mapping test in completions_test.go and
smaller cmd-level guards in try/run.
- Date validation on `--before` is deliberately the backend's job.
Mirroring Pydantic's date parser in Go would create silent skew
on minor backend bumps; the 422-detail surfacing already turns
bad input into an actionable message verbatim.
Architecture: introduces the first nested cobra group under `agents`
(`agents cache <verb>`). Phase 6+ reuse this for providers /
conversations / keys / domains. Per-verb sub-package wasn't worth it
for one verb; if `cache stats` etc. land later, split then.
Refactor on second use deferred deliberately: 4 new flags duplicate
mechanically across try.go and run.go (8 lines per command). Could
be extracted into a `RegisterCompletionFlags` helper, but try and run
are exactly two consumers and the duplication is straight-line. If a
third consumer appears, extract following the rule we've used since
Phase 3 (`PrintDryRun`, `NormalizeCompatibility`).
Coverage:
- `api/agentstudio/`: 1 new client method (`InvalidateAgentCache`),
extended `CompletionOptions`, table-driven wire-mapping test
covering all four flag combinations + the secure-user-token
header, four new cache-endpoint tests (no-before / with-before /
404→ErrNotFound / structured-422-detail surfaces verbatim).
- `pkg/cmd/agents/cache/`: new package, 6 unit tests covering happy
path, before-flag, dry-run with and without `--before`, missing
agent-id, non-TTY-without-confirm, and 404 propagation.
- `pkg/cmd/agents/try/` and `run/`: one targeted end-to-end test
each, asserting cobra→opts→client wiring is intact for all four
new flags (catches polarity transposition, missed forwarding).
- e2e: new `cache.txtar` (5 contract checks); `dry-run.txtar`
extended with a regression that the new `--no-*` flags are
wire-only and don't leak into the dry-run body preview.
Live verification deferred. Staging test app still has no LLM
provider configured, so a green completion isn't possible — but
cache invalidation doesn't depend on a provider, and the unit + e2e
coverage is exhaustive for the wire shapes. A future Phase 6 commit
that lands provider CRUD will revive the live-completion smoke.
Strategy: per-phase PR from here on. This branch
(`lab_week_3_phase5`) is cut from `lab_week_3` HEAD; the PR will
target `cmarguta-alg:lab_week_3` so the diff is bounded to Phase 5
only. When PR algolia#212 merges upstream, this PR's base re-targets to
`algolia:main`.
Net diff: +390 / −21 across 10 files, 2 new files (cache package,
cache.txtar). 13/13 agents packages green, all 4 e2e testscripts
pass (try / cache / dry-run / list-skipped-as-gated), gofumpt
clean, golangci-lint clean.
Co-authored-by: Cursor <cursoragent@cursor.com>
Owner
Author
|
Folding into PR algolia#212 — see algolia#212. Per-phase fork PRs added coordination overhead with no review benefit (PR algolia#212 is a draft pre-review). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 5 of the Agent Studio parity expansion. Closes the four completion query-param gaps and the cache-invalidate endpoint flagged by the parity audit against
https://agent-studio.eu.algolia.com/rag-openapi.json. Smallest delta of the planned phases — chosen first to validate the per-phase-PR rhythm without introducing brand-new architectural surface.Stacking note: this PR is intra-fork and bases on
lab_week_3(which is what PR algolia#212 targets upstream). When algolia#212 merges, this PR's base re-targets toalgolia:main.What's in
agents tryandagents runlearn--no-cache,--no-memory,--no-analytics, and--secure-user-token <jwt>. Maps onto the backend's documented completion query params + theX-Algolia-Secure-User-Tokenheader.agents cache invalidate <agent-id> [--before YYYY-MM-DD]wrapsDELETE /1/agents/{id}/cache. Mirrorsagents delete's confirmation contract: TTY prompts, non-TTY refuses without--confirm,--dry-runbypasses both since it's non-destructive.agents(agents cache <verb>). Phase 6+ will reuse this forproviders/conversations/keys/domains.Polarity calls worth knowing
CompletionOptions.No*fields are inverted from the wire on purpose. Backend defaults all three to true; only the negative is interesting at the CLI surface, andmemory=truewould 422 (the schema isanyOf [{const false}, {type null}]). Wire form omits the param when the No* field is false; sends<param>=falsewhen true. Pinned end-to-end by a table-driven wire-mapping test.--beforedate validation is deliberately the backend's job. Mirroring Pydantic's date parser in Go would create silent skew on minor backend bumps; the 422-detail surfacing already turns bad input into an actionable message verbatim.Refactor on second use deferred
Four new flags duplicate mechanically across
try.goandrun.go(8 lines per command). Could be extracted into aRegisterCompletionFlagshelper, but try and run are exactly two consumers and the duplication is straight-line. If a third consumer appears, extract following the rule we've used since Phase 3 (PrintDryRun,NormalizeCompatibility).Test plan
go test ./...— 73/73 packages green (was 72; +1agents/cache)go test -tags=e2e ./e2e -run TestAgents— 4 testscripts:try✓,cache✓ (new),dry-run✓ (extended),listskipped (env-gated)gofumpt -lclean acrossapi/agentstudio,pkg/cmd/agents,e2egolangci-lint runclean across the touched packagestask buildsucceedsalgolia agentsshows newcachegroup;algolia agents cacheshowsinvalidate;agents run --helpandagents try --helpshow the four new flagsNet diff
+736 / −21 across 13 files. 2 new files (
pkg/cmd/agents/cache/,e2e/testscripts/agents/cache.txtar).Made with Cursor