[codex] Expose agent harness selection decisions

[100yenadmin]

Summary

• Expose a pure resolveAgentHarnessSelection(...) decision object for the existing embedded harness selector.
• Keep the existing AgentHarness SPI and runtime behavior unchanged; selectAgentHarness(...) now delegates to the decision helper.
• Add structured debug logging from runAgentHarnessAttemptWithFallback(...) so operators can see selected harness id, policy runtime/fallback values, selection reason, and candidate support results.
• Document the observability path for diagnosing codex/* vs openai-codex/* routing without redesigning Pi/Codex harness selection.

Scope Guard

• This is the follow-up architecture/observability slice after PR [codex] Harden GPT-5.4 runtime paths #70743. It intentionally does not repeat the GPT-5.4 runtime fixes already implemented there.
• No provider routing, fallback behavior, app-server lifecycle, or public wire format changes.
• This supersedes PR [codex] Expose agent harness selection decisions #70750, whose fork branch ref updated correctly but whose PR object remained pinned to its old SHA/check run.

Validation

• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/harness/selection.test.ts
• pnpm tsgo:core:test
• pnpm exec oxlint src/agents/harness/selection.ts src/agents/harness/selection.test.ts
• pnpm exec oxfmt --check src/agents/harness/selection.ts src/agents/harness/selection.test.ts docs/plugins/sdk-agent-harness.md docs/plugins/codex-harness.md
• node scripts/run-vitest.mjs run --config test/vitest/vitest.full-core-support-boundary.config.ts test/scripts/lint-suppressions.test.ts
• git diff --check

Notes

• Current head: eb82cc910f.
• The debug record is emitted only when the agents/harness logger is debug-enabled.
• Auto-mode tests assert each plugin supports(...) method is still called exactly once per candidate.

[100yenadmin]

@steipete GPT 5.4 fixes

[greptile-apps]

Greptile Summary

This PR refactors selectAgentHarness to delegate to a new pure resolveAgentHarnessSelection helper that returns a structured AgentHarnessSelectionDecision object, then adds a gated log.debug call in runAgentHarnessAttemptWithFallback so operators can inspect the selected harness, policy values, and per-candidate support results without any behavior change. The existing SPI and public wire format are untouched, and the new tests confirm no duplicate supports(...) probes occur.

Confidence Score: 5/5

Safe to merge — no behavioral changes, all remaining findings are P2 style/cleanup suggestions.

The change is purely additive observability: a new exported decision type, a pure selection helper, and a debug-gated log call. Runtime paths are equivalent to before, existing tests still pass, and two new tests cover the auto-selection and pinned-PI paths. The only issues are a redundant intermediate .map() and a slightly misleading enum value name — both P2.

No files require special attention.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/agents/harness/selection.ts
Line: 138-142

Comment:
**Redundant intermediate `.map()` on `candidates`**

`candidates` already has the shape `{ harness: AgentHarness, support: AgentHarnessSupport }`. The `.map()` on lines 139–142 re-builds an identical object, adding an allocation with no transformation. The `.filter()` can operate on `candidates` directly.

```suggestion
  const supported = candidates
    .filter(
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/agents/harness/selection.ts
Line: 125

Comment:
**Misleading `selectedReason` value name**

`"forced_plugin_missing_pi_fallback"` reads as "the PI fallback is missing", but what actually happened is the opposite: the requested plugin harness is missing, so we are *using* the PI fallback. A name like `"forced_plugin_missing_fallback_pi"` or `"forced_plugin_fallback_to_pi"` would match the runtime semantics visible in the log record.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "feat: expose agent harness selection dec..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR improves observability of embedded agent harness selection by factoring the selection logic into an exported decision helper and emitting structured debug logs that explain why a harness was chosen (and what candidates were considered), without changing the existing AgentHarness SPI or runtime selection behavior.

Changes:

• Add resolveAgentHarnessSelection(...) to return a selection decision object (selected harness + policy + reason + candidate metadata), and update selectAgentHarness(...) to delegate to it.
• Add debug-gated structured logging in runAgentHarnessAttemptWithFallback(...) to record selection details.
• Update plugin docs to describe the new observability path for diagnosing PI vs Codex harness routing.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/agents/harness/selection.ts	Exposes selection decision helper and emits structured debug logs during embedded runs.
src/agents/harness/selection.test.ts	Adds tests for decision observability and ensures no duplicate supports(...) probes.
docs/plugins/sdk-agent-harness.md	Documents the structured selection log record for debugging routing decisions.
docs/plugins/codex-harness.md	Adds guidance on using the selection log record to spot model-prefix mismatches.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[Copilot]

resolveAgentHarnessSelection(...) is described in the PR as exposing a “pure” decision object, but AgentHarnessSelectionDecision includes a live harness: AgentHarness reference (functions, potentially non-serializable). This makes it awkward to safely persist/emit/JSON-serialize the decision (and increases the risk of accidental logging of function bodies or large closures). Consider returning the selected harness separately (e.g., { harness, decision }) or making the exported decision type omit harness and instead expose only selectedHarnessId/label plus candidates/policy.

[steipete]

Landed via squash onto main.

• Source head: 100yenadmin@fe39f12
• Merge commit: 137dbc7
• Gates: focused local harness tests/format/lint plus GitHub checks green.

Thanks @100yenadmin!