feat(server): add --lazy-source-init to connect sources on first use

[akangsha7]

Description

Toolbox connects to every configured source at startup and aborts the process if any single connection fails. That is the right default for a small, always-used set of sources, but it means a tool catalog cannot be inspected without provisioning its databases, cold start pays for every source a config declares rather than every source it uses, and one bad credential produces an MCP server that silently never comes up.

This adds an opt-in --lazy-source-init flag. It is off by default and the eager path is untouched. When set, each source connects on the first tool call that needs it.

Where the laziness lives. The sources.Source interface carries no database-specific methods, so 271 of the 273 tool packages downcast the injected source to their own package-private interface, across 755 assertion sites. No wrapper type can satisfy 271 independently-declared private interfaces, so a proxy would fail every tool's assertion at runtime. Instead a SourceResolver sits between the invocation handlers and the primitive store and connects on demand; the concrete, fully-connected source still reaches the tool untouched and no tool code changes.

PrimitiveManager stays a plain get/set repository — it gains only SetSource. Keeping the fallible, I/O-performing lookup off the store is deliberate, so the store remains substitutable by a backend-backed implementation later.

Two lookup contracts. Listing paths (tools/list, /api/toolset) call the non-blocking GetSource and fall back to the tool's static manifest when a source has not been reached yet. Invocation paths (tools/call, /api/tool/invoke) call SourceResolver.Resolve. Only invocation handlers receive the resolver, so a listing handler cannot block on a connect. The rule does not branch on the flag: under eager init Resolve returns on its first line with no I/O.

Three properties worth calling out:

• Concurrent first calls are coalesced. singleflight collapses N simultaneous first calls into one connection attempt, so an agent issuing parallel tool calls against a cold source does not open N pools.
• The shared attempt is bounded and detached from its callers. It runs on context.WithoutCancel of the starting caller's context, capped at 60s. Each caller waits on its own context, so a caller returns on its own request deadline; a caller that gives up does not abort the attempt for everyone else.
• Failures are not cached. A source that was down starts working on a later call without a restart.

Startup validation is split, not removed. A tool naming a source that does not exist is still a startup error. Tool/source type compatibility is deferred to first call, since asserting it requires a live source.

Connection failure is agent-visible. An unreachable source returns a tool result with isError: true rather than a JSON-RPC protocol error, which most client harnesses consume before the model ever sees it. Over REST the same failure is a 503.

Env var placeholders. Under the flag, an unset required ${VAR} resolves to its own name as a non-empty placeholder so required-string validation still passes, and startup logs a warning naming every substitution. Without the flag a missing variable remains a hard startup error. The end state is that ./toolbox --prebuilt alloydb-postgres --lazy-source-init serves the full catalog with no database, no credentials, and no environment variables set.

Known limitations

Raising these explicitly rather than leaving them to be discovered:

• Placeholders only work for string-typed fields. Substitution is a text pass over the YAML before unmarshalling, so an unset ${VAR} on an int or bool field (for example database: ${REDIS_DB}) produces a bare scalar and the config fails to unmarshal — the server refuses to start. All 38 prebuilt configs are unaffected, so the documented flow works, but user-authored configs using ${VAR} on typed fields will hit this.
• Config reload is not atomic. The source configs and the primitive store are updated under different locks. They are now installed in the order that makes the worst case a discarded connect rather than a stale source cached for the process lifetime, but a combined API would be needed to close the window properly.
• Reload drops warm sources. Under lazy init every reload leaves the sources map empty, so the next call re-pays a cold connect even for a reload that changed nothing about sources. Related pre-existing issue: sources.Source has no Close(), so discarded pools are not torn down on either the eager or lazy reload path.
• No notifications/tools/list_changed. A tool whose schema is derived from a live source advertises its static schema until that source connects. Clients that listed beforehand are not told when the resolved schema becomes available.

Non-goals

Partial-availability/health semantics, retry or backoff policy, negative caching of failed connections, adding Close() to the source interface, and making lazy the default.

Test plan

• go test -race ./cmd/... ./internal/... — 358 packages, no failures
• golangci-lint run --timeout 10m — 0 issues
• go mod tidy && git diff --exit-code
• Unit tests for the resolver: connect-when-cold, connect-when-warm, unknown source, concurrent first-call coalescing, caller-cancellation isolation, caller deadline, and no-caching-of-failures
• Unit tests for the static manifest fallback, one per protocol version
• Unit test that a connection failure yields an isError tool result rather than a protocol error
• Regression: the existing suite passes unchanged with the flag unset
• Manual: ./toolbox --prebuilt alloydb-postgres --lazy-source-init with no database, credentials, or env vars set; confirm the catalog lists and a tool call returns a readable error
• Drive it from a real MCP client to confirm the agent receives readable isError content rather than a protocol-level failure

PR Checklist

• Make sure to open an issue as a bug/issue before writing your code!
• Ensure the tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)
• Make sure to add ! if this involves a breaking change

[gemini-code-assist]

Code Review

This pull request introduces a --lazy-source-init flag that defers connecting to configured sources until they are first used, allowing the server to start up and serve tool catalogs even when sources are unreachable or required environment variables are missing. To support this, a new SourceResolver is introduced to manage lazy connections, and tool listing and invocation paths are updated to fall back to static manifests when a source is not yet connected. The feedback suggests checking if the context is already canceled before initiating a connection attempt in the resolver to avoid spawning unnecessary goroutines.

[gemini-code-assist]

It is recommended to check if the caller's context (ctx) is already canceled or expired before initiating the connection attempt via singleflight. This prevents spawning unnecessary background connection goroutines when the request has already been abandoned by the client.

Suggested change

	}
	}
	if err := ctx.Err(); err != nil {
	return nil, fmt.Errorf("unable to initialize source %q: %w", sourceName, err)
	}