Skip to content

feat(rag): decouple indexing from caller timeout via indexing_timeout config (#4073) - #4172

Merged
dgageot merged 1 commit into
mainfrom
feat/4073-rag-indexing-timeout
Sep 4, 2026
Merged

dgageot merged 1 commit into
mainfrom
feat/4073-rag-indexing-timeout

Conversation

@aheritier

Copy link
Copy Markdown
Collaborator

Part of #4073 (T2+T3), depends on #4158 (merged — atomic per-file persistence, T1).

Problem

tools.DefaultStartTimeout (30s) is a shared wait budget for detecting wedged toolsets of any type (#4001). rag.ToolSet.Start honoured the caller's cancellation for manager.Initialize, so when a large knowledge base's indexing outlived the 30s budget, in-flight embedding work (and, pre-#4158, correctness) was discarded and the next turn re-started from scratch.

Fix

Extend the detachment pattern already used for the RAG file watcher (context.WithoutCancel) to manager.Initialize. Indexing now runs on a context derived from the detached watcher context, bounded only by:

  • a new indexing_timeout config on RAGConfig (default 30m, 0s = unbounded), and
  • the toolset's own Stop.

tools.DefaultStartTimeout's value and the #4062 backoff logic are unchanged — only a clarifying doc comment was added. Raising the shared constant would regress wedged-toolset detection for every toolset type; the fix belongs in RAG's own Start.

#4062 invariant preserved (regression-tested): a detached 429/408/5xx from the model provider during indexing still arms the backoff gate; an indexing_timeout expiry is context.DeadlineExceeded (non-retryable) and never arms it, so the next turn resumes immediately.

Behavior change

Large-KB first turn(s) now proceed without the RAG tool (same UX as any wedged toolset today) instead of blocking up to 30s. Files finished before the budget expires are persisted (per #4158); the tool appears once indexing completes on a later turn.

Changes

  • pkg/config/latest/{types,validate}.go: RAGConfig.IndexingTimeout *Duration + GetIndexingTimeout(); negative values rejected, including for top-level rag: blocks (which bypass Toolset.validate() during unmarshal).
  • agent-schema.json, examples/rag/semantic_embeddings.yaml, docs/tools/rag/index.md: schema/example/docs for indexing_timeout.
  • pkg/tools/builtin/rag/rag.go: WithIndexingTimeout option; Start builds initCtx from the detached watcher context.
  • pkg/tools/startable.go: doc-only clarification on DefaultStartTimeout.
  • Tests: pkg/tools/builtin/rag/rag_indexing_timeout_test.go (new), rag_backoff_test.go (extended), pkg/config/latest/rag_test.go (new).

Testing

task lint and task test (incl. -race on the rag package) pass clean.

… config

Extend the detachment pattern already used for the RAG file watcher
(context.WithoutCancel) to manager.Initialize, so the 30s toolset-start
wait budget (tools.DefaultStartTimeout, shared by all toolset types for
#4001 wedged-toolset detection) no longer aborts in-flight indexing.
When the caller gives up waiting, indexing keeps running in the
background under the single-flight lock and a later turn picks up the
toolset once it finishes.

Indexing itself is now bounded by a new indexing_timeout config
(pkg/config/latest.RAGConfig, default 30m, "0s" = unbounded) instead
of the caller's ctx, so a hung provider connection cannot pin the
indexing lock forever.

Regression tests prove the #4062 backoff-gate invariants hold: a 429
returned by detached indexing still arms the gate, while an
indexing_timeout deadline (context.DeadlineExceeded, non-retryable)
does not.

Part of #4073, depends on #4158 (atomic per-file persistence).
@aheritier
aheritier marked this pull request as ready for review September 4, 2026 13:58
@aheritier
aheritier requested a review from a team as a code owner September 4, 2026 13:58
@dgageot
dgageot merged commit 44ca37b into main Sep 4, 2026
22 checks passed
@dgageot
dgageot deleted the feat/4073-rag-indexing-timeout branch September 4, 2026 13:59
social4hyq pushed a commit to social4hyq/homebrew-core that referenced this pull request Sep 20, 2026
docker-agent 1.134.0

Created-by: HarmonybrewBot
Commit-by: HarmonybrewBot
Merged-by: HarmonybrewBot
Description: Created by `brew bump`

---

Created with `brew bump-formula-pr`.<details>
  <summary>release notes</summary>
  <pre>This release adds machine-readable output to debug commands, improves RAG indexing reliability, fixes config handling for removed fields, and includes a large batch of documentation corrections.

## What's New

- Adds `--json` flag to `debug toolsets` and `debug skills` subcommands for machine-readable output
- Accepts positional flavor names on `debug config` (e.g., `docker agent debug config examples/flavors.yaml cheap with-shell`)
- Decouples RAG indexing from the caller timeout via a new `indexing_timeout` config option, preventing large knowledge base indexing from being discarded when the 30s startup budget is exceeded
- Pins the injected docker-agent image to the host CLI version by default in `docker agent eval`

## Bug Fixes

- Fixes config upgrade hinting at removed fields (e.g., `safer`) instead of silently re-adding them
- Always records the resolved agent image in saved eval run JSON
- Bounds the SSRF pre-check DNS lookup in `desktopAwareTransport` to 2 seconds to prevent hangs on corporate networks
- Replaces removed `github-copilot/gpt-4.1` model with `gpt-5.5` in the models snapshot

## Technical Changes

- Freezes config schema v15 as an immutable package and advances `latest` to v16
- Refreshes the embedded models.dev catalog snapshot (129 models added, 67 removed, ~322 updated)
- Corrects 53 documentation inaccuracies across 34 files covering SDK examples, CLI flags, telemetry, permissions, and integrations
---

## What's Changed
* docs: update CHANGELOG.md for v1.133.0 by @docker-read-write[bot] in docker/docker-agent#4171
* feat(rag): decouple indexing from caller timeout via indexing_timeout config (#4073) by @aheritier in docker/docker-agent#4172
* feat(debug): add --json flag to debug toolsets and skills by @dgageot in docker/docker-agent#4173
* feat(debug): accept positional flavors on `debug config` by @dgageot in docker/docker-agent#4174
* chore: refresh models.dev snapshot (+129 -67 ~322) by @github-actions[bot] in docker/docker-agent#4183
* docs: auto-update for merged PRs (2026-09-05) by @aheritier in docker/docker-agent#4178
* fix(config): hint at removed fields instead of re-adding them by @aheritier in docker/docker-agent#4177
* feat(eval): pin injected docker-agent image to host CLI version by default by @aheritier in docker/docker-agent#4176
* docs: fix inaccuracies across SDK examples, CLI flags, telemetry, permissions, and integrations by @dgageot in docker/docker-agent#4184
* fix(http): bound the SSRF pre-check DNS lookup in desktopAwareTransport by @trungutt in docker/docker-agent#4186


**Full Changelog**: docker/docker-agent@v1.133.0...v1.134.0
</pre>
  <p>View the full release notes at <a href="https://github.com/docker/docker-agent/releases/tag/v1.134.0">https://github.com/docker/docker-agent/releases/tag/v1.134.0</a>.</p>
</details>
<hr>

See merge request: Harmonybrew/homebrew-core!18592
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants