diff --git a/src/application/binary/BinarySessionRestoration.test.ts b/src/application/binary/BinarySessionRestoration.test.ts index 900bdc6da0..a9030a91cf 100644 --- a/src/application/binary/BinarySessionRestoration.test.ts +++ b/src/application/binary/BinarySessionRestoration.test.ts @@ -87,6 +87,9 @@ it.each([false, true])( analysis_provider_binding: { selection_source: "auto-single-candidate", }, + analysis_provider_candidates: [ + { selected: true, selection_source: "auto-single-candidate" }, + ], }); expect((await session.execute("list_strings", {})).ok).toBe(true); expect(starts).toEqual([0, 1]); diff --git a/src/application/binary/BinarySessionStatus.test.ts b/src/application/binary/BinarySessionStatus.test.ts index 0661b53db6..712ee49180 100644 --- a/src/application/binary/BinarySessionStatus.test.ts +++ b/src/application/binary/BinarySessionStatus.test.ts @@ -672,43 +672,59 @@ it("keeps host unavailability ahead of target applicability", async () => { ]); }); +/** A rejected candidate whose diagnostic text must not reach the summary. */ +const unavailableReport = { + provider: providerB, + status: { + code: "not_configured" as const, + reason: "PROVIDER_B_HOME is not set.", + remediation: "Set PROVIDER_B_HOME; see docs/provider-b.md.", + }, + support: { + code: "architecture_unsupported" as const, + reason: "Provider B cannot select this slice.", + }, +}; +const rejectedCandidate = ( + report: typeof unavailableReport, +): AnalysisProviderCandidateStatus => ({ + ...candidate(providerB, otherCapabilities), + availability: { + status: "unavailable", + code: report.status.code, + reason: report.status.reason, + remediation: report.status.remediation, + diagnostics: { checks: [{ name: "configuration", ok: false }] }, + }, + targetSupport: { + status: "unsupported", + code: report.support.code, + reason: report.support.reason, + diagnostics: { architecture: "arm64" }, + }, + selected: false, + selectionSource: null, + rejections: [ + { + providerId: providerB.id, + origin: "availability", + code: report.status.code, + reason: report.status.reason, + remediation: report.status.remediation, + diagnostics: { checks: [{ name: "configuration", ok: false }] }, + }, + { + providerId: providerB.id, + origin: "target", + code: report.support.code, + reason: report.support.reason, + diagnostics: { architecture: "arm64" }, + }, + ], +}); + describe("binary session summary projection", () => { it("keeps each candidate's status, code and reason in summary without diagnostics or capability sets", async () => { - const unavailable: AnalysisProviderCandidateStatus = { - ...candidate(providerB, otherCapabilities), - availability: { - status: "unavailable", - code: "not_configured", - reason: "PROVIDER_B_HOME is not set.", - remediation: "Set PROVIDER_B_HOME; see docs/provider-b.md.", - diagnostics: { checks: [{ name: "configuration", ok: false }] }, - }, - targetSupport: { - status: "unsupported", - code: "architecture_unsupported", - reason: "Provider B cannot select this slice.", - diagnostics: { architecture: "arm64" }, - }, - selected: false, - selectionSource: null, - rejections: [ - { - providerId: providerB.id, - origin: "availability", - code: "not_configured", - reason: "PROVIDER_B_HOME is not set.", - remediation: "Set PROVIDER_B_HOME; see docs/provider-b.md.", - diagnostics: { checks: [{ name: "configuration", ok: false }] }, - }, - { - providerId: providerB.id, - origin: "target", - code: "architecture_unsupported", - reason: "Provider B cannot select this slice.", - diagnostics: { architecture: "arm64" }, - }, - ], - }; const pending: AnalysisProviderCandidateStatus = { ...candidate(providerA, selectedCapabilities), availability: { @@ -718,7 +734,7 @@ describe("binary session summary projection", () => { diagnostics: { startup: "pending" }, }, }; - const candidates = [pending, unavailable]; + const candidates = [pending, rejectedCandidate(unavailableReport)]; const before = structuredClone(candidates); const runtimeUnavailability = new Map([ ["procedure_info", { reason: "Runtime operation failure" }], @@ -733,6 +749,7 @@ describe("binary session summary projection", () => { detail: "summary", }); const summary = summaryStatusSchema.parse(raw); + const { status, support } = unavailableReport; expect(candidates).toEqual(before); expect(summary.capabilities).toEqual(complete.capabilities); @@ -750,30 +767,72 @@ describe("binary session summary projection", () => { reason: "No target is open.", }, selected: true, + selection_source: "auto-single-candidate", + rejections: [], }, { provider: providerB, availability: { status: "unavailable", - code: "not_configured", - reason: "PROVIDER_B_HOME is not set.", + code: status.code, + reason: status.reason, }, target_support: { status: "unsupported", - code: "architecture_unsupported", - reason: "Provider B cannot select this slice.", + code: support.code, + reason: support.reason, }, selected: false, + selection_source: null, + rejections: [ + { + provider_id: providerB.id, + origin: "availability", + code: status.code, + reason: status.reason, + }, + { + provider_id: providerB.id, + origin: "target", + code: support.code, + reason: support.reason, + }, + ], }, ]); expect(JSON.stringify(raw)).not.toContain("diagnostics"); + // Complete detail keeps the owner's repair copy on each rejection. + expect(complete.analysis_provider_candidates[1]?.rejections).toEqual([ + { + provider_id: providerB.id, + origin: "availability", + code: status.code, + reason: status.reason, + remediation: status.remediation, + diagnostics: { checks: [{ name: "configuration", ok: false }] }, + }, + { + provider_id: providerB.id, + origin: "target", + code: support.code, + reason: support.reason, + diagnostics: { architecture: "arm64" }, + }, + ]); // Complete detail keeps the owner's repair; summary omits it. expect( complete.analysis_provider_candidates[1]?.availability, - ).toMatchObject({ - remediation: "Set PROVIDER_B_HOME; see docs/provider-b.md.", - }); + ).toMatchObject({ remediation: status.remediation }); expect(JSON.stringify(raw)).not.toContain("PROVIDER_B_HOME;"); + // Summary keeps every rejection code and reason but never its repair text. + expect( + summary.analysis_provider_candidates[1]?.rejections.map( + ({ origin, code, reason }) => ({ origin, code, reason }), + ), + ).toEqual([ + { origin: "availability", code: status.code, reason: status.reason }, + { origin: "target", code: support.code, reason: support.reason }, + ]); expect( analysisProviderCandidate .array() diff --git a/src/application/binary/BinarySessionStatus.ts b/src/application/binary/BinarySessionStatus.ts index 8f54e1aa22..afbb9b396f 100644 --- a/src/application/binary/BinarySessionStatus.ts +++ b/src/application/binary/BinarySessionStatus.ts @@ -27,6 +27,7 @@ import type { import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js"; import type { BinarySessionDetail } from "../../contracts/sessionStatusContract.js"; import type { AnalysisCleanupRetry } from "../../domain/analysisErrorRecovery.js"; +import type { ProviderSelectionRejection } from "../../domain/providerSelectionError.js"; interface BinarySessionStatusInput { readonly investigation: InvestigationStatistics; @@ -134,12 +135,16 @@ export const binarySessionStatus = async ({ availability: providerStateSummary(candidate.availability), target_support: providerStateSummary(candidate.targetSupport), selected: candidate.selected, + selection_source: candidate.selectionSource, + rejections: candidate.rejections.map(rejectionSummary), } : { provider: providerSummary(candidate.provider), availability: structuredClone(candidate.availability), target_support: structuredClone(candidate.targetSupport), selected: candidate.selected, + selection_source: candidate.selectionSource, + rejections: candidate.rejections.map(selectionRejection), capabilities: providerCapabilitySets( candidate.capabilities .slice() @@ -323,6 +328,36 @@ const providerSummary = ({ readonly version: string | null; }) => ({ id, name, version }); +/** Carry every rejection fact at complete detail; clones keep the caller's copy immutable. */ +const selectionRejection = ({ + providerId, + origin, + code, + reason, + remediation, + diagnostics, +}: ProviderSelectionRejection) => ({ + provider_id: providerId, + origin, + code, + reason, + ...(remediation === undefined ? {} : { remediation }), + diagnostics: structuredClone(diagnostics), +}); + +/** Rejection codes and reasons stay at summary detail; repair and diagnostics do not. */ +const rejectionSummary = ({ + providerId, + origin, + code, + reason, +}: ProviderSelectionRejection) => ({ + provider_id: providerId, + origin, + code, + reason, +}); + const processLineageStatus = ( snapshots: readonly ProviderRuntimeLineageSnapshot[], ) => diff --git a/src/application/binary/SessionProviderRouter.ts b/src/application/binary/SessionProviderRouter.ts index 33f25accd1..e7571ffb01 100644 --- a/src/application/binary/SessionProviderRouter.ts +++ b/src/application/binary/SessionProviderRouter.ts @@ -139,23 +139,27 @@ export class SessionProviderRouter { } = {}, ): Promise { const { signal, target, refresh = false } = options; - if (refresh && route.selection !== undefined) { - const current = await this.registry.candidates( - target, - signal === undefined ? {} : { signal }, - ); - return current.map((candidate) => ({ + const candidates = + refresh && route.selection !== undefined + ? await this.registry.candidates( + target, + signal === undefined ? {} : { signal }, + ) + : (route.selection?.candidates ?? + (await this.registry.candidates( + undefined, + signal === undefined ? {} : { signal }, + ))); + const binding = route.binding; + if (binding === null) return candidates; + return candidates.map((candidate) => { + const selected = candidate.provider.id === binding.identity.id; + return { ...candidate, - selected: candidate.provider.id === route.binding?.identity.id, - })); - } - return ( - route.selection?.candidates ?? - this.registry.candidates( - undefined, - signal === undefined ? {} : { signal }, - ) - ); + selected, + selectionSource: selected ? binding.selectionSource : null, + }; + }); } /** Produce exact candidate rejections for an intentionally unbound route. */ diff --git a/src/contracts/sessionStatusContract.ts b/src/contracts/sessionStatusContract.ts index a188b53a08..329b82d051 100644 --- a/src/contracts/sessionStatusContract.ts +++ b/src/contracts/sessionStatusContract.ts @@ -13,6 +13,8 @@ export const BINARY_SESSION_SUMMARY_OMITTED_FIELDS = [ "analysis_provider_candidates.availability.remediation", "analysis_provider_candidates.availability.diagnostics", "analysis_provider_candidates.target_support.diagnostics", + "analysis_provider_candidates.rejections.remediation", + "analysis_provider_candidates.rejections.diagnostics", "analysis_provider_candidates.capabilities", "tool_availability.groups.surface", "tool_availability.groups.effects", @@ -25,7 +27,7 @@ export const binarySessionInputSchema = z.strictObject({ .enum(BINARY_SESSION_DETAILS) .default("summary") .describe( - "Start with summary (default): it keeps open state, the binding, current-route capabilities (including selected Ghidra checkpoint mode), each provider candidate's availability and target-support status, code and reason, and every tool's availability, reason and remediation; omitted_fields lists what it leaves out. Request complete only when you need unavailable-candidate remediation, provider diagnostics, candidate capabilities or static tool surface, effect and annotation flags.", + "Start with summary (default): it keeps open state, the binding, current-route capabilities (including selected Ghidra checkpoint mode), each provider candidate's selection source, availability and target-support status, code and reason with its rejection codes, and every tool's availability, reason and remediation; omitted_fields lists what it leaves out. Request complete only when you need unavailable-candidate remediation, provider or rejection diagnostics, candidate capabilities or static tool surface, effect and annotation flags.", ), refresh_candidates: z .boolean() diff --git a/src/contracts/toolOutputSchemaPrimitives.ts b/src/contracts/toolOutputSchemaPrimitives.ts index c212cbe3c4..069dfffc3f 100644 --- a/src/contracts/toolOutputSchemaPrimitives.ts +++ b/src/contracts/toolOutputSchemaPrimitives.ts @@ -345,16 +345,34 @@ const providerTargetSupport = z.discriminatedUnion("status", [ }), ]); +/** Where a selected provider's choice came from; never a priority or fallback. */ +const analysisProviderSelectionSource = z.enum([ + "request", + "environment", + "auto-single-candidate", +]); + +const providerSelectionRejection = z.object({ + provider_id: z.string(), + origin: z.enum(["availability", "target"]), + code: z.string().min(1), + reason: z.string().min(1), + remediation: providerRemediation.exactOptional(), + diagnostics: jsonObjectSchema, +}); + /** Complete candidate facts, including provider-owned diagnostics and capability sets. */ export const analysisProviderCandidate = z.object({ provider: providerIdentity, availability: providerAvailability, target_support: providerTargetSupport, selected: z.boolean(), + selection_source: analysisProviderSelectionSource.nullable(), + rejections: z.array(providerSelectionRejection), capabilities: z.array(providerCapabilitySet), }); -/** Summary candidate: the same status, code, and reason without remediation, diagnostics or capabilities. */ +/** Summary candidate: the same status, code, reason and rejection codes without remediation, diagnostics or capabilities. */ export const analysisProviderCandidateSummary = z.strictObject({ provider: providerIdentity, availability: z.discriminatedUnion("status", [ @@ -368,6 +386,15 @@ export const analysisProviderCandidateSummary = z.strictObject({ providerTargetSupportStates.unsupported.strict(), ]), selected: z.boolean(), + selection_source: analysisProviderSelectionSource.nullable(), + rejections: z.array( + z.strictObject({ + provider_id: z.string(), + origin: z.enum(["availability", "target"]), + code: z.string().min(1), + reason: z.string().min(1), + }), + ), }); const clientFeatureNameSchema = z.enum([ diff --git a/tests/boundary/cli/directAnalysisStatus.test.ts b/tests/boundary/cli/directAnalysisStatus.test.ts index 5dc56375b1..28ff7c949c 100644 --- a/tests/boundary/cli/directAnalysisStatus.test.ts +++ b/tests/boundary/cli/directAnalysisStatus.test.ts @@ -148,3 +148,114 @@ it.each(["capabilities", "providers"])( }); }, ); + +it.each(["capabilities", "providers"])( + "exposes each candidate's selection source and rejections through %s", + async (command) => { + const session = createStatusSession(); + const status = vi.spyOn(session, "status").mockResolvedValueOnce({ + open: false, + capabilities: [], + analysis_provider_binding: null, + analysis_provider_candidates: [ + { + provider: { id: "fixture", name: "Fixture", version: "1" }, + availability: { + status: "available", + code: null, + reason: null, + diagnostics: {}, + }, + target_support: { + status: "unknown", + code: null, + reason: "No target is open.", + diagnostics: {}, + }, + selected: true, + selection_source: "auto-single-candidate", + rejections: [], + capabilities: [], + }, + { + provider: { id: "other", name: "Other", version: null }, + availability: { + status: "unavailable", + code: "not_configured", + reason: "OTHER_HOME is not set.", + remediation: "Set OTHER_HOME.", + diagnostics: { checks: [] }, + }, + target_support: { + status: "unknown", + code: null, + reason: "No target is open.", + diagnostics: {}, + }, + selected: false, + selection_source: null, + rejections: [ + { + provider_id: "other", + origin: "availability", + code: "not_configured", + reason: "OTHER_HOME is not set.", + remediation: "Set OTHER_HOME.", + diagnostics: { checks: [] }, + }, + ], + capabilities: [], + }, + ], + }); + const cli = Cli.create({ name: "rea" }); + registerUtilityCommands( + cli, + silentLogger, + {}, + { + runSessionStatus: () => + runSessionStatus({ + readConfiguration: () => parseConfig({}), + createBinarySession: () => session, + }), + runProviderAnalysis: async () => ({ ok: false, error: null }), + }, + ); + let stdout = ""; + try { + await cli.serve([command, "--json"], { + env: {}, + stdout: (text) => { + stdout += text; + }, + exit: () => {}, + }); + expect(JSON.parse(stdout)).toMatchObject({ + analysis_provider_candidates: [ + { + provider: { id: "fixture" }, + selection_source: "auto-single-candidate", + rejections: [], + }, + { + provider: { id: "other" }, + selection_source: null, + rejections: [ + { + provider_id: "other", + origin: "availability", + code: "not_configured", + reason: "OTHER_HOME is not set.", + remediation: "Set OTHER_HOME.", + }, + ], + }, + ], + }); + } finally { + status.mockRestore(); + await session.close(); + } + }, +); diff --git a/tests/boundary/mcp/providerSelectionMcp.test.ts b/tests/boundary/mcp/providerSelectionMcp.test.ts index 61a6ff4424..9f09ae44f5 100644 --- a/tests/boundary/mcp/providerSelectionMcp.test.ts +++ b/tests/boundary/mcp/providerSelectionMcp.test.ts @@ -146,6 +146,32 @@ const expectUnknownProviderKeepsBinding = async ( ); }; +const expectRefreshedExplicitBinding = async (mcp: Client): Promise => { + for (const detail of ["summary", "complete"] as const) { + const refreshed = structured( + await mcp.callTool({ + name: "binary_session", + arguments: { detail, refresh_candidates: true }, + }), + ); + expect(refreshed.result).toMatchObject({ + analysis_provider_binding: { selection_source: "request" }, + analysis_provider_candidates: [ + { + provider: { id: "alpha" }, + selected: false, + selection_source: null, + }, + { + provider: { id: "beta" }, + selected: true, + selection_source: "request", + }, + ], + }); + } +}; + describe("provider selection over MCP", () => { it("keeps open_binary and binary_session binding semantics exact", async () => { const directory = await createTestTempDirectory("rea-provider-mcp-"); @@ -286,6 +312,9 @@ describe("provider selection over MCP", () => { ], }); + await expectRefreshedExplicitBinding(mcp); + expect(starts).toEqual(["beta"]); + await expectUnknownProviderKeepsBinding( mcp, session, @@ -415,24 +444,43 @@ const candidateStatus = (candidates: unknown) => z .array(z.record(z.string(), z.unknown())) .parse(candidates) - .map(({ provider, selected, availability, target_support }) => { - const state = (value: unknown) => { - const { status, code, reason } = z - .object({ - status: z.string(), - code: z.unknown(), - reason: z.unknown(), - }) - .parse(value); - return { status, code, reason }; - }; - return { + .map( + ({ provider, selected, - availability: state(availability), - target_support: state(target_support), - }; - }), + selection_source, + availability, + target_support, + rejections, + }) => { + const state = (value: unknown) => { + const { status, code, reason } = z + .object({ + status: z.string(), + code: z.unknown(), + reason: z.unknown(), + }) + .parse(value); + return { status, code, reason }; + }; + return { + provider, + selected, + selection_source, + availability: state(availability), + target_support: state(target_support), + rejections: z + .array(z.record(z.string(), z.unknown())) + .parse(rejections) + .map(({ provider_id, origin, code, reason }) => ({ + provider_id, + origin, + code, + reason, + })), + }; + }, + ), ); const expectSummaryKeepsDecisionFacts = (