feat(logging): add a trace tier across all plugins, unlocked by DEBUG

[stephane-segning]

What

Adds a most-verbose trace log level (priority 5, below debug) to all four plugins, plus ~85 fine-grained trace events at the points worth watching when debugging. Answers "can we get A LOT more logs?" — yes, and they all surface at --log-level DEBUG.

How it's gated

The tier is high-volume, so it isn't a separate host knob: OpenCode's DEBUG now maps to trace (fromOpenCodeLogLevel("DEBUG") → "trace"). Running the host at --log-level DEBUG unlocks the full trace stream on top of the existing debug lifecycle events. A clean run at the default info stays quiet.

OpenCode's client.app.log() enum has no trace, so a trace record is forwarded to the host labelled debug (the finer gating already happened locally); the JSON-console fallback keeps the true trace label. All four plugins converged on this independently.

Events by plugin

• oauth2 (~26): config-hook steps, providers considered/registered/skipped, token cache load, ensureAccessToken branches (reuse/refresh/interactive), refresh + model-discovery start/finish, per-request bearer injection, scheduler ticks.
• models-info (~16): per-provider meta parse, cache key/lookup, fetch start, per-model match + field-merge (upstream-wins) decisions, counts.
• ratelimit (~16): per-provider opt-in, wrapped-fetch invocation + scope bucket key, parsed x-ratelimit triple, throttle/tier selection, pre-emptive wait, 429 backoff/retry, cooldown set/cleared.
• browser (~28): handshake steps, every frame routed (agent→executor), command dispatch/result/timeout, group ownership (assign/deny/adopt/orphan), executor/agent connect/disconnect, host/guest election.

No secrets: redaction applies to trace like every level; events carry booleans/counts/ids, never raw tokens.

Infra + tests + docs

• Per package: LogLevel union, LOG_LEVEL_PRIORITY, Logger.trace, console logger, OpenCode wrapper. Plus oauth2 validateLogLevel accepts "trace", and the browser-mcp logger literal gained trace.
• Each package's logging.test.ts covers DEBUG → trace, trace-emits-at-trace / suppressed-at-debug, and the working trace method.
• docs/architecture.md → Logging gains a "trace tier" section.

Full pre-push gate green: pnpm -r build && pnpm -r typecheck && pnpm coverage && pnpm lint && pnpm format:check (every per-package coverage threshold still met; 449 tests pass).

Branches off main; independent of #54 and #55 except the shared ## [Unreleased] changelog block (trivial merge).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[gemini-code-assist]

Code Review

This pull request introduces a new, highly detailed trace log tier across all workspace packages, allowing fine-grained tracking of internal operations when the host is run with --log-level DEBUG. The review feedback focuses on optimizing the performance of the newly added trace logging logic in packages/opencode-models-info/src/plugin.ts by eliminating redundant Map lookups and avoiding double-filtering of array fields.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

We can optimize the Map lookups here by retrieving the value directly with byId.get(modelId) instead of calling byId.has(modelId) first. This avoids an extra Map lookup on every iteration of the loop.

Suggested change

	const matchById = byId.has(modelId);
	const match = byId.get(modelId) ?? (declaredId ? byId.get(declaredId) : undefined);
	if (!match) {
	deps.logger.trace("models_info_model_unmatched", { providerId, modelId, declaredId });
	continue;
	}
	deps.logger.trace("models_info_model_matched", {
	providerId,
	modelId,
	matchedBy: matchById ? "id" : "declaredId"
	const matchFromId = byId.get(modelId);
	const match = matchFromId ?? (declaredId ? byId.get(declaredId) : undefined);
	if (!match) {
	deps.logger.trace("models_info_model_unmatched", { providerId, modelId, declaredId });
	continue;
	}
	deps.logger.trace("models_info_model_matched", {
	providerId,
	modelId,
	matchedBy: matchFromId ? "id" : "declaredId"
	});

[gemini-code-assist]

Evaluating derivedFields.filter twice (including an $O(N)$ .includes check inside the second filter) on every model iteration creates unnecessary array allocations and overhead, even when trace logging is disabled. We can optimize this by partitioning the fields in a single pass.

      const derivedFields = Object.keys(derived);
      const appliedFields: string[] = [];
      const skippedFields: string[] = [];
      for (const f of derivedFields) {
        if (modelConfig[f] === undefined || overwrite?.has(f)) {
          appliedFields.push(f);
        } else {
          skippedFields.push(f);
        }
      }