perf(mcp)!: compact repeated session discovery facts (#1988)
Group repeated session tool availability and provider capability facts, preserve complete named contracts and ordered limitations, and remove duplicate catalog descriptors. Update consumers and migration guidance. Validated by all 31 CI jobs, focused source checks, and actual Claude Code/Linux Hopper/native Windows Ghidra small-target workflows on the current integration tree. Refs #723. BREAKING CHANGE: binary_session no longer includes server_identity.catalog.tools; tool_availability and provider capabilities use grouped facts documented in docs/mcp-contracts.md. Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
This commit is contained in:
@@ -0,0 +1,391 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import type {
|
||||
CapabilityDescriptor,
|
||||
ProviderIdentity,
|
||||
} from "../AnalysisProvider.js";
|
||||
import {
|
||||
expandProviderCapabilities,
|
||||
type ProviderCapabilitySet,
|
||||
} from "../../contracts/toolOutputSchemaPrimitives.js";
|
||||
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
|
||||
import type { AnalysisProviderCandidateStatus } from "./AnalysisProviderRegistry.js";
|
||||
import type {
|
||||
SessionProviderRoute,
|
||||
SessionProviderRouter,
|
||||
} from "./SessionProviderRouter.js";
|
||||
import { binarySessionStatus } from "./BinarySessionStatus.js";
|
||||
|
||||
type ProjectedStatus = {
|
||||
capabilities: ProviderCapabilitySet[];
|
||||
analysis_provider_candidates: {
|
||||
provider: ProviderIdentity;
|
||||
availability: unknown;
|
||||
target_support: unknown;
|
||||
selected: boolean;
|
||||
capabilities: ProviderCapabilitySet[];
|
||||
}[];
|
||||
};
|
||||
|
||||
const providerA: ProviderIdentity = {
|
||||
id: "provider-a",
|
||||
name: "Provider A",
|
||||
version: "1.0",
|
||||
};
|
||||
const providerB: ProviderIdentity = {
|
||||
id: "provider-b",
|
||||
name: "Provider B",
|
||||
version: "2.0",
|
||||
};
|
||||
|
||||
const MUTATING_EFFECTS = {
|
||||
mutates_artifact: true,
|
||||
launches_process: false,
|
||||
may_show_ui: false,
|
||||
may_access_network: false,
|
||||
may_write_filesystem: false,
|
||||
changes_permissions: false,
|
||||
requires_root: false,
|
||||
};
|
||||
|
||||
type DescriptorOptions = {
|
||||
readonly launchesProcess?: boolean;
|
||||
} & (
|
||||
| {
|
||||
readonly available?: true;
|
||||
readonly reason?: never;
|
||||
readonly availabilityCode?: never;
|
||||
}
|
||||
| {
|
||||
readonly available: false;
|
||||
readonly reason?: string;
|
||||
readonly availabilityCode?: "architecture_unsupported";
|
||||
}
|
||||
);
|
||||
|
||||
const descriptor = (
|
||||
provider: ProviderIdentity,
|
||||
operation: CapabilityDescriptor["operation"],
|
||||
limitations: readonly string[],
|
||||
options: DescriptorOptions = {},
|
||||
): CapabilityDescriptor => {
|
||||
const availability =
|
||||
options.available === false
|
||||
? {
|
||||
available: false as const,
|
||||
reason: options.reason ?? "Unavailable",
|
||||
...(options.availabilityCode === undefined
|
||||
? {}
|
||||
: { availabilityCode: options.availabilityCode }),
|
||||
}
|
||||
: { available: true as const, reason: null };
|
||||
return {
|
||||
provider,
|
||||
operation,
|
||||
...availability,
|
||||
effects: {
|
||||
mutatesArtifact: true,
|
||||
launchesProcess: options.launchesProcess ?? false,
|
||||
mayShowUi: false,
|
||||
mayAccessNetwork: false,
|
||||
mayWriteFilesystem: false,
|
||||
changesPermissions: false,
|
||||
requiresRoot: false,
|
||||
},
|
||||
limitations,
|
||||
};
|
||||
};
|
||||
|
||||
const candidate = (
|
||||
provider: ProviderIdentity,
|
||||
capabilities: readonly CapabilityDescriptor[],
|
||||
): AnalysisProviderCandidateStatus => ({
|
||||
provider,
|
||||
availability: {
|
||||
status: "available",
|
||||
code: null,
|
||||
reason: null,
|
||||
diagnostics: {},
|
||||
},
|
||||
targetSupport: {
|
||||
status: "unknown",
|
||||
code: null,
|
||||
reason: "No target is open.",
|
||||
diagnostics: {},
|
||||
},
|
||||
selected: true,
|
||||
capabilities,
|
||||
});
|
||||
|
||||
const project = (
|
||||
routeCapabilities: readonly CapabilityDescriptor[],
|
||||
candidates: readonly AnalysisProviderCandidateStatus[],
|
||||
runtimeUnavailability: ReadonlyMap<
|
||||
string,
|
||||
{ readonly reason: string }
|
||||
> = new Map(),
|
||||
): ProjectedStatus => {
|
||||
const route = {
|
||||
capabilities: new Map(
|
||||
routeCapabilities.map((capability) => [capability.operation, capability]),
|
||||
),
|
||||
binding: null,
|
||||
} as unknown as SessionProviderRoute;
|
||||
const router = {
|
||||
candidateStatuses: () => candidates,
|
||||
} as unknown as SessionProviderRouter;
|
||||
return binarySessionStatus({
|
||||
target: undefined,
|
||||
route,
|
||||
router,
|
||||
runtimeUnavailability,
|
||||
runId: undefined,
|
||||
runtimeLineageSnapshots: [],
|
||||
requestActivitySnapshots: [],
|
||||
}) as unknown as ProjectedStatus;
|
||||
};
|
||||
|
||||
const expandCanonicalCapabilities = (sets: readonly ProviderCapabilitySet[]) =>
|
||||
[...expandProviderCapabilities(sets)].sort((left, right) =>
|
||||
compareUnicodeCodePoints(left.operation, right.operation),
|
||||
);
|
||||
|
||||
const selectedCapabilities = [
|
||||
descriptor(providerA, "xrefs", ["Shared limitation"]),
|
||||
descriptor(providerA, "procedure_info", ["Shared limitation"]),
|
||||
descriptor(providerA, "read_bytes", ["Shared limitation", "beta detail"]),
|
||||
];
|
||||
const otherCapabilities = [
|
||||
descriptor(providerB, "read_bytes", ["Different limitation"], {
|
||||
launchesProcess: true,
|
||||
available: false,
|
||||
reason: "Architecture unsupported",
|
||||
availabilityCode: "architecture_unsupported",
|
||||
}),
|
||||
];
|
||||
|
||||
const expectedRouteCapabilities: ProviderCapabilitySet[] = [
|
||||
{
|
||||
provider: providerA,
|
||||
shared_limitations: ["Shared limitation"],
|
||||
groups: [
|
||||
{
|
||||
operations: ["procedure_info"],
|
||||
effects: ["mutates_artifact"],
|
||||
limitations: [],
|
||||
available: false,
|
||||
reason: "Runtime operation failure",
|
||||
availability_code: null,
|
||||
},
|
||||
{
|
||||
operations: ["read_bytes"],
|
||||
effects: ["mutates_artifact"],
|
||||
limitations: ["beta detail"],
|
||||
available: true,
|
||||
reason: null,
|
||||
availability_code: null,
|
||||
},
|
||||
{
|
||||
operations: ["xrefs"],
|
||||
effects: ["mutates_artifact"],
|
||||
limitations: [],
|
||||
available: true,
|
||||
reason: null,
|
||||
availability_code: null,
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
const expectedExpandedRouteCapabilities = [
|
||||
{
|
||||
provider: providerA,
|
||||
operation: "procedure_info",
|
||||
available: false,
|
||||
reason: "Runtime operation failure",
|
||||
availability_code: null,
|
||||
effects: MUTATING_EFFECTS,
|
||||
limitations: ["Shared limitation"],
|
||||
},
|
||||
{
|
||||
provider: providerA,
|
||||
operation: "read_bytes",
|
||||
available: true,
|
||||
reason: null,
|
||||
availability_code: null,
|
||||
effects: MUTATING_EFFECTS,
|
||||
limitations: ["Shared limitation", "beta detail"],
|
||||
},
|
||||
{
|
||||
provider: providerA,
|
||||
operation: "xrefs",
|
||||
available: true,
|
||||
reason: null,
|
||||
availability_code: null,
|
||||
effects: MUTATING_EFFECTS,
|
||||
limitations: ["Shared limitation"],
|
||||
},
|
||||
];
|
||||
const expectedCandidateCapabilities: ProviderCapabilitySet[] = [
|
||||
{
|
||||
provider: providerA,
|
||||
shared_limitations: ["Shared limitation"],
|
||||
groups: [
|
||||
{
|
||||
operations: ["procedure_info", "xrefs"],
|
||||
effects: ["mutates_artifact"],
|
||||
limitations: [],
|
||||
available: true,
|
||||
reason: null,
|
||||
availability_code: null,
|
||||
},
|
||||
{
|
||||
operations: ["read_bytes"],
|
||||
effects: ["mutates_artifact"],
|
||||
limitations: ["beta detail"],
|
||||
available: true,
|
||||
reason: null,
|
||||
availability_code: null,
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
provider: providerB,
|
||||
shared_limitations: ["Different limitation"],
|
||||
groups: [
|
||||
{
|
||||
operations: ["read_bytes"],
|
||||
effects: ["mutates_artifact", "launches_process"],
|
||||
limitations: [],
|
||||
available: false,
|
||||
reason: "Architecture unsupported",
|
||||
availability_code: "architecture_unsupported",
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
const expectedCandidateStatusFacts = [
|
||||
expect.objectContaining({
|
||||
provider: providerA,
|
||||
target_support: {
|
||||
status: "unknown",
|
||||
code: null,
|
||||
reason: "No target is open.",
|
||||
diagnostics: {},
|
||||
},
|
||||
capabilities: [expectedCandidateCapabilities[0]],
|
||||
}),
|
||||
expect.objectContaining({
|
||||
provider: providerB,
|
||||
capabilities: [expectedCandidateCapabilities[1]],
|
||||
}),
|
||||
];
|
||||
const expectedExpandedCandidateCapabilities = [
|
||||
[
|
||||
{
|
||||
provider: providerA,
|
||||
operation: "procedure_info",
|
||||
available: true,
|
||||
reason: null,
|
||||
availability_code: null,
|
||||
effects: MUTATING_EFFECTS,
|
||||
limitations: ["Shared limitation"],
|
||||
},
|
||||
{
|
||||
provider: providerA,
|
||||
operation: "read_bytes",
|
||||
available: true,
|
||||
reason: null,
|
||||
availability_code: null,
|
||||
effects: MUTATING_EFFECTS,
|
||||
limitations: ["Shared limitation", "beta detail"],
|
||||
},
|
||||
{
|
||||
provider: providerA,
|
||||
operation: "xrefs",
|
||||
available: true,
|
||||
reason: null,
|
||||
availability_code: null,
|
||||
effects: MUTATING_EFFECTS,
|
||||
limitations: ["Shared limitation"],
|
||||
},
|
||||
],
|
||||
[
|
||||
{
|
||||
provider: providerB,
|
||||
operation: "read_bytes",
|
||||
available: false,
|
||||
reason: "Architecture unsupported",
|
||||
availability_code: "architecture_unsupported",
|
||||
effects: { ...MUTATING_EFFECTS, launches_process: true },
|
||||
limitations: ["Different limitation"],
|
||||
},
|
||||
],
|
||||
];
|
||||
|
||||
describe("binary session provider capability projection", () => {
|
||||
it("preserves provider scope and route overlays while factoring exact prefixes", () => {
|
||||
const selectedBefore = structuredClone(selectedCapabilities);
|
||||
const otherBefore = structuredClone(otherCapabilities);
|
||||
const status = project(
|
||||
selectedCapabilities,
|
||||
[
|
||||
candidate(providerA, selectedCapabilities),
|
||||
candidate(providerB, otherCapabilities),
|
||||
],
|
||||
new Map([["procedure_info", { reason: "Runtime operation failure" }]]),
|
||||
);
|
||||
expect(selectedCapabilities).toEqual(selectedBefore);
|
||||
expect(otherCapabilities).toEqual(otherBefore);
|
||||
expect(status.capabilities).toEqual(expectedRouteCapabilities);
|
||||
expect(expandCanonicalCapabilities(status.capabilities)).toEqual(
|
||||
expectedExpandedRouteCapabilities,
|
||||
);
|
||||
expect(status.analysis_provider_candidates).toEqual(
|
||||
expectedCandidateStatusFacts,
|
||||
);
|
||||
const selectedCandidate = status.analysis_provider_candidates[0];
|
||||
const otherCandidate = status.analysis_provider_candidates[1];
|
||||
expect(selectedCandidate).toBeDefined();
|
||||
expect(otherCandidate).toBeDefined();
|
||||
expect(
|
||||
expandCanonicalCapabilities(selectedCandidate?.capabilities ?? []),
|
||||
).toEqual(expectedExpandedCandidateCapabilities[0]);
|
||||
expect(
|
||||
expandCanonicalCapabilities(otherCandidate?.capabilities ?? []),
|
||||
).toEqual(expectedExpandedCandidateCapabilities[1]);
|
||||
});
|
||||
|
||||
it("keeps empty route and candidate capability collections empty", () => {
|
||||
const status = project([], [candidate(providerA, [])]);
|
||||
expect(status.capabilities).toEqual([]);
|
||||
expect(status.analysis_provider_candidates[0]?.capabilities).toEqual([]);
|
||||
});
|
||||
|
||||
it("preserves repeated limitations in their original order", () => {
|
||||
const capabilities = [
|
||||
descriptor(providerA, "procedure_info", [
|
||||
"Repeated",
|
||||
"Repeated",
|
||||
"left detail",
|
||||
]),
|
||||
descriptor(providerA, "xrefs", ["Repeated", "Repeated", "right detail"]),
|
||||
];
|
||||
const status = project(capabilities, []);
|
||||
|
||||
expect(status.capabilities[0]).toMatchObject({
|
||||
shared_limitations: ["Repeated", "Repeated"],
|
||||
groups: [
|
||||
{ operations: ["procedure_info"], limitations: ["left detail"] },
|
||||
{ operations: ["xrefs"], limitations: ["right detail"] },
|
||||
],
|
||||
});
|
||||
expect(
|
||||
expandCanonicalCapabilities(status.capabilities).map(
|
||||
({ limitations }) => limitations,
|
||||
),
|
||||
).toEqual([
|
||||
["Repeated", "Repeated", "left detail"],
|
||||
["Repeated", "Repeated", "right detail"],
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -4,9 +4,14 @@ import type { JsonValue } from "../../domain/jsonValue.js";
|
||||
import type { ProviderOperationHealth } from "../../domain/providerOperationHealth.js";
|
||||
import type {
|
||||
CapabilityDescriptor,
|
||||
ProviderIdentity,
|
||||
ProviderRequestActivitySnapshot,
|
||||
ProviderRuntimeLineageSnapshot,
|
||||
} from "../AnalysisProvider.js";
|
||||
import {
|
||||
PROVIDER_EFFECT_NAMES,
|
||||
type ProviderCapabilitySet,
|
||||
} from "../../contracts/toolOutputSchemaPrimitives.js";
|
||||
import type {
|
||||
SessionProviderRoute,
|
||||
SessionProviderRouter,
|
||||
@@ -38,7 +43,7 @@ export const binarySessionStatus = ({
|
||||
requestActivitySnapshots,
|
||||
providerOperationHealth,
|
||||
}: BinarySessionStatusInput): JsonValue => {
|
||||
const capabilities = [...route.capabilities.values()]
|
||||
const routeCapabilities = [...route.capabilities.values()]
|
||||
.filter(({ operation }) => operation !== "inventory_artifact")
|
||||
.sort((left, right) =>
|
||||
compareUnicodeCodePoints(left.operation, right.operation),
|
||||
@@ -52,8 +57,8 @@ export const binarySessionStatus = ({
|
||||
available: false as const,
|
||||
reason: unavailable.reason,
|
||||
};
|
||||
})
|
||||
.map(capabilityStatus);
|
||||
});
|
||||
const capabilities = providerCapabilitySets(routeCapabilities);
|
||||
const analysisProviderBinding =
|
||||
route.binding === null
|
||||
? null
|
||||
@@ -69,13 +74,14 @@ export const binarySessionStatus = ({
|
||||
availability: structuredClone(candidate.availability),
|
||||
target_support: structuredClone(candidate.targetSupport),
|
||||
selected: candidate.selected,
|
||||
capabilities: candidate.capabilities
|
||||
.slice()
|
||||
.filter(({ operation }) => operation !== "inventory_artifact")
|
||||
.sort((left, right) =>
|
||||
compareUnicodeCodePoints(left.operation, right.operation),
|
||||
)
|
||||
.map(capabilityStatus),
|
||||
capabilities: providerCapabilitySets(
|
||||
candidate.capabilities
|
||||
.slice()
|
||||
.filter(({ operation }) => operation !== "inventory_artifact")
|
||||
.sort((left, right) =>
|
||||
compareUnicodeCodePoints(left.operation, right.operation),
|
||||
),
|
||||
),
|
||||
}));
|
||||
const common = {
|
||||
capabilities,
|
||||
@@ -187,17 +193,109 @@ const processLineageStatus = (
|
||||
})),
|
||||
};
|
||||
|
||||
const capabilityStatus = (
|
||||
descriptor: Omit<CapabilityDescriptor, "available" | "reason"> & {
|
||||
readonly available: boolean;
|
||||
readonly reason: string | null;
|
||||
},
|
||||
) => ({
|
||||
operation: descriptor.operation,
|
||||
available: descriptor.available,
|
||||
reason: descriptor.reason,
|
||||
availability_code: descriptor.availabilityCode ?? null,
|
||||
effects: {
|
||||
type CapabilityEffectName = (typeof PROVIDER_EFFECT_NAMES)[number];
|
||||
type CapabilityAvailabilityCode = Exclude<
|
||||
CapabilityDescriptor["availabilityCode"],
|
||||
undefined
|
||||
>;
|
||||
type CapabilityProjection = Omit<CapabilityDescriptor, "available" | "reason"> &
|
||||
(
|
||||
| { readonly available: true; readonly reason: null }
|
||||
| { readonly available: false; readonly reason: string }
|
||||
);
|
||||
type ProviderCapabilityGroup = ProviderCapabilitySet["groups"][number];
|
||||
|
||||
/** Group inline capability facts without merging distinct providers or states. */
|
||||
const providerCapabilitySets = (
|
||||
descriptors: readonly CapabilityProjection[],
|
||||
): ProviderCapabilitySet[] => {
|
||||
const providers = new Map<
|
||||
string,
|
||||
{
|
||||
readonly identity: ProviderIdentity;
|
||||
readonly descriptors: CapabilityProjection[];
|
||||
}
|
||||
>();
|
||||
for (const descriptor of descriptors) {
|
||||
const key = JSON.stringify([
|
||||
descriptor.provider.id,
|
||||
descriptor.provider.name,
|
||||
descriptor.provider.version,
|
||||
]);
|
||||
const provider = providers.get(key);
|
||||
if (provider === undefined)
|
||||
providers.set(key, {
|
||||
identity: descriptor.provider,
|
||||
descriptors: [descriptor],
|
||||
});
|
||||
else provider.descriptors.push(descriptor);
|
||||
}
|
||||
return [...providers.values()].map(({ identity, descriptors: owned }) => {
|
||||
const sharedLimitations = commonLimitationsPrefix(owned);
|
||||
const groups = new Map<string, ProviderCapabilityGroup>();
|
||||
for (const descriptor of owned) {
|
||||
const effects = enabledCapabilityEffects(descriptor);
|
||||
const limitations = descriptor.limitations.slice(
|
||||
sharedLimitations.length,
|
||||
);
|
||||
const availabilityCode: CapabilityAvailabilityCode | null =
|
||||
descriptor.availabilityCode ?? null;
|
||||
const status = descriptor.available
|
||||
? {
|
||||
available: true as const,
|
||||
reason: null,
|
||||
availability_code: null,
|
||||
}
|
||||
: {
|
||||
available: false as const,
|
||||
reason: descriptor.reason,
|
||||
availability_code: availabilityCode,
|
||||
};
|
||||
const key = JSON.stringify([
|
||||
effects,
|
||||
limitations,
|
||||
status.available,
|
||||
status.reason,
|
||||
status.availability_code,
|
||||
]);
|
||||
const group = groups.get(key);
|
||||
if (group === undefined)
|
||||
groups.set(key, {
|
||||
operations: [descriptor.operation],
|
||||
effects,
|
||||
limitations,
|
||||
...status,
|
||||
});
|
||||
else group.operations.push(descriptor.operation);
|
||||
}
|
||||
return {
|
||||
provider: providerSummary(identity),
|
||||
shared_limitations: sharedLimitations,
|
||||
groups: [...groups.values()],
|
||||
};
|
||||
});
|
||||
};
|
||||
|
||||
const commonLimitationsPrefix = (
|
||||
descriptors: readonly CapabilityProjection[],
|
||||
): string[] => {
|
||||
const first = descriptors[0]?.limitations;
|
||||
if (first === undefined) return [];
|
||||
let length = first.length;
|
||||
for (const descriptor of descriptors.slice(1)) {
|
||||
length = Math.min(length, descriptor.limitations.length);
|
||||
let index = 0;
|
||||
while (index < length && first[index] === descriptor.limitations[index])
|
||||
index++;
|
||||
length = index;
|
||||
}
|
||||
return first.slice(0, length);
|
||||
};
|
||||
|
||||
const enabledCapabilityEffects = (
|
||||
descriptor: CapabilityProjection,
|
||||
): CapabilityEffectName[] => {
|
||||
const effectValues = {
|
||||
mutates_artifact: descriptor.effects.mutatesArtifact,
|
||||
launches_process: descriptor.effects.launchesProcess,
|
||||
may_show_ui: descriptor.effects.mayShowUi,
|
||||
@@ -205,9 +303,9 @@ const capabilityStatus = (
|
||||
may_write_filesystem: descriptor.effects.mayWriteFilesystem,
|
||||
changes_permissions: descriptor.effects.changesPermissions,
|
||||
requires_root: descriptor.effects.requiresRoot,
|
||||
},
|
||||
limitations: [...descriptor.limitations],
|
||||
});
|
||||
} satisfies Record<CapabilityEffectName, boolean>;
|
||||
return PROVIDER_EFFECT_NAMES.filter((name) => effectValues[name]);
|
||||
};
|
||||
|
||||
const providerOperationHealthStatus = (
|
||||
health: ProviderOperationHealth | null | undefined,
|
||||
|
||||
Reference in New Issue
Block a user