feat(session): add explicit provider registry and target binding

Introduce deterministic deep-provider discovery and immutable per-target routing while retaining disjoint artifact and native capability families.

Expose provider selection consistently through MCP, CLI, environment configuration, session status, prompt completion, typed diagnostics, and generated documentation. Preserve exact provider/profile provenance without request racing or transparent fallback.

Cover overlapping providers, ambiguity, rejection details, cancellation, restoration, package installation, and real Hopper target switching.
This commit is contained in:
N0zoM1z0
2026-07-15 22:13:48 +09:00
committed by N0zoM1z0
parent bd3cf964d6
commit 941d7101dd
174 changed files with 5370 additions and 648 deletions
+417
View File
@@ -0,0 +1,417 @@
import { describe, expect, it } from "vitest";
import {
AnalysisProviderRegistry,
type AnalysisProviderBinding,
} from "../src/application/AnalysisProviderRegistry.js";
import {
createAnalysisExecution,
type AnalysisClient,
type AnalysisProviderCandidate,
type CapabilityDescriptor,
type ProviderAvailability,
type ProviderIdentity,
type ProviderTargetSupport,
} from "../src/application/AnalysisProvider.js";
import { createAnalysisProfile } from "../src/domain/analysisProfile.js";
import type { BinaryTarget } from "../src/domain/binaryTarget.js";
import {
ProviderAdapterError,
ProviderSelectionError,
projectAnalysisError,
} from "../src/domain/errors.js";
import { err, ok } from "../src/domain/result.js";
const DATABASE_TARGET: BinaryTarget = {
path: "/tmp/fixture.hop",
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
};
const ARTIFACT_TARGET: BinaryTarget = {
path: "/tmp/app.asar",
sha256: "b".repeat(64),
kind: "archive",
format: "asar",
};
describe("analysis provider registry", () => {
it("admits overlapping operations, sorts discovery, and rejects duplicate IDs", () => {
const alpha = candidate("alpha");
const beta = candidate("beta");
const registry = new AnalysisProviderRegistry([
beta.provider,
alpha.provider,
]);
expect(registry.identities().map(({ id }) => id)).toEqual([
"alpha",
"beta",
]);
expect(
registry.candidates().map(({ provider, targetSupport }) => ({
id: provider.id,
support: targetSupport.status,
})),
).toEqual([
{ id: "alpha", support: "unknown" },
{ id: "beta", support: "unknown" },
]);
expect(alpha.created).toEqual([]);
expect(beta.created).toEqual([]);
expect(
() => new AnalysisProviderRegistry([alpha.provider, alpha.provider]),
).toThrow(/Duplicate analysis provider ID: alpha/u);
expect(
() =>
new AnalysisProviderRegistry([
{
...alpha.provider,
capabilities: () => {
const descriptor = capability(alpha.provider.identity());
return [descriptor, descriptor];
},
},
]),
).toThrow(/declares operation address_name more than once/u);
expect(
() =>
new AnalysisProviderRegistry([
{
...alpha.provider,
capabilities: () => [
capability({
...alpha.provider.identity(),
name: "mismatched provider",
}),
],
},
]),
).toThrow(/published mismatched capability provenance/u);
expect(
() => new AnalysisProviderRegistry([candidate("auto").provider]),
).toThrow(/Invalid analysis provider ID: auto/u);
});
it("selects the sole usable candidate without creating a client", async () => {
const alpha = candidate("alpha");
const beta = candidate("beta", { available: false });
const registry = new AnalysisProviderRegistry([
beta.provider,
alpha.provider,
]);
const selected = await registry.select(DATABASE_TARGET);
expect(selected.ok).toBe(true);
if (!selected.ok || selected.value.binding === null) return;
expect(bindingProjection(selected.value.binding)).toEqual({
id: "alpha",
source: "auto-single-candidate",
version: "1",
});
expect(selected.value.candidates).toMatchObject([
{ provider: { id: "alpha", version: "1" }, selected: true },
{
provider: { id: "beta" },
selected: false,
availability: { status: "unavailable", code: "runtime_missing" },
},
]);
expect(alpha.created).toEqual([]);
expect(beta.created).toEqual([]);
});
it("makes auto ambiguity explicit and honors request over environment", async () => {
const alpha = candidate("alpha");
const beta = candidate("beta");
const registry = new AnalysisProviderRegistry(
[alpha.provider, beta.provider],
"beta",
);
const environment = await registry.select(DATABASE_TARGET);
expect(environment.ok).toBe(true);
if (environment.ok)
expect(environment.value.binding?.selectionSource).toBe("environment");
expect(environment.ok && environment.value.binding?.identity.id).toBe(
"beta",
);
const request = await registry.select(DATABASE_TARGET, "alpha");
expect(request.ok && request.value.binding?.identity.id).toBe("alpha");
if (request.ok)
expect(request.value.binding?.selectionSource).toBe("request");
const automatic = await registry.select(DATABASE_TARGET, "auto");
expect(automatic.ok).toBe(false);
if (automatic.ok) return;
expect(automatic.error).toMatchObject({
reason: "ambiguous",
requestedProviderId: "auto",
candidateIds: ["alpha", "beta"],
});
expect(projectAnalysisError(automatic.error)).toMatchObject({
code: "capability_unavailable",
details: {
selection_reason: "ambiguous",
candidate_ids: ["alpha", "beta"],
},
});
expect(alpha.created).toEqual([]);
expect(beta.created).toEqual([]);
});
it("returns actionable unknown, unavailable, and unsupported failures", async () => {
const unavailable = candidate("alpha", { available: false });
const registry = new AnalysisProviderRegistry([unavailable.provider]);
const unknown = await registry.select(DATABASE_TARGET, "missing");
expect(unknown.ok).toBe(false);
if (!unknown.ok)
expect(projectAnalysisError(unknown.error)).toMatchObject({
details: {
selection_reason: "unknown_provider",
requested_provider_id: "missing",
candidate_ids: ["alpha"],
},
});
const rejected = await registry.select(DATABASE_TARGET, "alpha");
expect(rejected.ok).toBe(false);
if (!rejected.ok)
expect(projectAnalysisError(rejected.error)).toMatchObject({
code: "provider_unavailable",
details: {
rejections: [
{
provider_id: "alpha",
code: "runtime_missing",
diagnostics: { executable_path: "/opt/alpha/bin/analyze" },
},
],
},
});
const unsupported = await new AnalysisProviderRegistry([
candidate("alpha", { available: false }).provider,
]).select(ARTIFACT_TARGET, "alpha");
expect(unsupported.ok).toBe(false);
if (
!unsupported.ok &&
unsupported.error instanceof ProviderSelectionError
) {
expect(unsupported.error).toMatchObject({ reason: "target_unsupported" });
expect(unsupported.error.rejections.map(({ code }) => code)).toEqual([
"runtime_missing",
"target_kind_unsupported",
]);
}
});
it("keeps artifact-only targets unbound under auto or environment preference", async () => {
const alpha = candidate("alpha");
const environment = new AnalysisProviderRegistry([alpha.provider], "alpha");
const automatic = new AnalysisProviderRegistry([alpha.provider]);
for (const registry of [environment, automatic]) {
const selected = await registry.select(ARTIFACT_TARGET);
expect(selected).toMatchObject({
ok: true,
value: {
binding: null,
candidates: [
{
selected: false,
targetSupport: {
status: "unsupported",
code: "target_kind_unsupported",
},
},
],
},
});
}
const explicit = await automatic.select(ARTIFACT_TARGET, "alpha");
expect(explicit.ok).toBe(false);
if (!explicit.ok && explicit.error instanceof ProviderSelectionError)
expect(explicit.error.reason).toBe("target_unsupported");
});
it("does not bind a profile with unresolved version or adapter failure", async () => {
const unresolved = candidate("unresolved", { profile: "missing" });
const failed = candidate("failed", { profile: "error" });
const automatic = await new AnalysisProviderRegistry([
unresolved.provider,
]).select(DATABASE_TARGET);
expect(automatic).toMatchObject({
ok: true,
value: {
binding: null,
candidates: [
{
availability: {
status: "unavailable",
code: "version_unresolved",
},
},
],
},
});
const explicit = await new AnalysisProviderRegistry([
failed.provider,
]).select(DATABASE_TARGET, "failed");
expect(explicit.ok).toBe(false);
if (!explicit.ok && explicit.error instanceof ProviderSelectionError)
expect(explicit.error.rejections).toMatchObject([
{
providerId: "failed",
code: "version_unresolved",
diagnostics: { error_tag: "ProviderAdapterError" },
},
]);
});
it("cancels a pending profile probe even when the adapter ignores its signal", async () => {
const alpha = candidate("alpha");
let observedSignal: AbortSignal | undefined;
const ignoresCancellation: AnalysisProviderCandidate = {
...alpha.provider,
resolveAnalysisProfile: (_target, options) => {
observedSignal = options?.signal;
return new Promise<never>(() => undefined);
},
};
const controller = new AbortController();
const selecting = new AnalysisProviderRegistry([
ignoresCancellation,
]).select(DATABASE_TARGET, "alpha", { signal: controller.signal });
expect(observedSignal).toBe(controller.signal);
controller.abort();
await expect(selecting).resolves.toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError", operation: "open_binary" },
});
expect(alpha.created).toEqual([]);
});
});
interface CandidateFixture {
readonly provider: AnalysisProviderCandidate;
readonly created: string[];
}
const candidate = (
id: string,
options: {
readonly available?: boolean;
readonly profile?: "resolved" | "missing" | "error";
} = {},
): CandidateFixture => {
const identity: ProviderIdentity = {
id,
name: `${id} provider`,
version: null,
};
const created: string[] = [];
const available = options.available ?? true;
const provider: AnalysisProviderCandidate = {
identity: () => identity,
capabilities: () => [capability(identity)],
inspectAvailability: (): ProviderAvailability =>
available
? {
status: "available",
code: null,
reason: null,
diagnostics: { executable_path: `/opt/${id}/bin/analyze` },
}
: {
status: "unavailable",
code: "runtime_missing",
reason: `${id} runtime is unavailable`,
diagnostics: { executable_path: `/opt/${id}/bin/analyze` },
},
inspectTargetSupport: (target): ProviderTargetSupport =>
target.kind === "database"
? {
status: "supported",
code: null,
reason: null,
diagnostics: { target_kind: target.kind },
}
: {
status: "unsupported",
code: "target_kind_unsupported",
reason: `${id} only accepts analysis databases in this fixture`,
diagnostics: { target_kind: target.kind },
},
resolveAnalysisProfile: () => {
if (options.profile === "error")
return Promise.resolve(
err(new ProviderAdapterError(id, "resolve_analysis_profile")),
);
return Promise.resolve(
ok({
profile:
options.profile === "missing"
? null
: createAnalysisProfile(
{ id, name: identity.name, version: "1" },
1,
{ fixture: id },
),
compatibility: {},
}),
);
},
createClient: (_target, profile): AnalysisClient => {
created.push(id);
const executionIdentity = profile?.provider ?? identity;
return {
execute: (operation) =>
Promise.resolve(
ok(
createAnalysisExecution(
operation === "health" ? null : `${id}:${operation}`,
executionIdentity,
),
),
),
close: () => Promise.resolve(),
};
},
};
return { provider, created };
};
const capability = (provider: ProviderIdentity): CapabilityDescriptor => ({
provider,
operation: "address_name",
inputContractVersion: 1,
outputContractVersion: 1,
available: true,
reason: null,
pagination: "none",
exhaustive: true,
effects: {
mutatesArtifact: false,
launchesProcess: true,
mayShowUi: false,
mayAccessNetwork: false,
mayWriteFilesystem: false,
changesPermissions: false,
requiresRoot: false,
},
limits: { maxResults: null, maxPayloadBytes: 1_000, timeoutMs: 1_000 },
limitations: [],
});
const bindingProjection = (binding: AnalysisProviderBinding) => ({
id: binding.identity.id,
source: binding.selectionSource,
version: binding.identity.version,
});
+29
View File
@@ -558,6 +558,35 @@ describe("binary session", () => {
expect(created).toBe(1);
});
it("cancels legacy profile resolution even when the provider ignores its signal", async () => {
const [first] = await targets();
const provider = cacheProvider([]);
let observedSignal: AbortSignal | undefined;
let created = 0;
provider.resolveAnalysisProfile = (_target, options) => {
observedSignal = options?.signal;
return new Promise<never>(() => undefined);
};
provider.createClient = () => {
created += 1;
return new TestClient();
};
const session = new BinarySession(provider);
const controller = new AbortController();
const opening = session.open(first, { signal: controller.signal });
while (observedSignal === undefined)
await new Promise<void>((resolve) => setImmediate(resolve));
expect(observedSignal).toBe(controller.signal);
controller.abort();
await expect(opening).resolves.toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError", operation: "open_binary" },
});
expect(created).toBe(0);
});
it("cancels a call while it waits for a transition", async () => {
const [first] = await targets();
const health = deferred<ReturnType<typeof ok>>();
+4
View File
@@ -58,6 +58,10 @@ describe("composite analysis provider", () => {
});
expect(hopperCalls).toEqual(["address_name"]);
expect(nativeCalls).toEqual(["analyze_function"]);
expect(await client.execute("list_names", {})).toMatchObject({
ok: false,
error: { _tag: "AnalysisCapabilityUnavailableError" },
});
});
it("publishes exact operation provenance and rejects ambiguous routes", () => {
+17 -1
View File
@@ -6,7 +6,10 @@ describe("runtime configuration", () => {
it("allows target-free startup and defaults to Hopper's documented launcher", () => {
const empty = parseConfig({});
expect(empty.ok).toBe(true);
if (empty.ok) expect(empty.value.hopperTargetPath).toBeUndefined();
if (empty.ok) {
expect(empty.value.hopperTargetPath).toBeUndefined();
expect(empty.value.analysisProvider).toBe("auto");
}
const result = parseConfig({ HOPPER_TARGET_PATH: "/usr/bin/true" });
expect(result.ok).toBe(true);
if (result.ok) {
@@ -35,6 +38,19 @@ describe("runtime configuration", () => {
}
});
it("parses one shared provider selector and rejects unstable IDs", () => {
expect(parseConfig({ REA_ANALYSIS_PROVIDER: "ghidra" })).toMatchObject({
ok: true,
value: { analysisProvider: "ghidra" },
});
expect(parseConfig({ REA_ANALYSIS_PROVIDER: "auto" })).toMatchObject({
ok: true,
value: { analysisProvider: "auto" },
});
for (const invalid of ["", "Auto", "ghidra_1", "ghidra "])
expect(parseConfig({ REA_ANALYSIS_PROVIDER: invalid }).ok).toBe(false);
});
it("builds a separate Electron endpoint and file-root ceiling", () => {
const result = parseConfig({
REA_ELECTRON_OBSERVE_ENABLED: "true",
+29 -1
View File
@@ -1,4 +1,4 @@
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -32,11 +32,39 @@ afterEach(async () => {
});
describe("direct analysis snapshot permissions", () => {
it("forwards the CLI provider selector ahead of the environment preference", async () => {
directory = await mkdtemp(join(tmpdir(), "rea-direct-provider-"));
const targetPath = join(directory, "fixture.hop");
await writeFile(targetPath, "fixture");
vi.stubEnv("HOPPER_LAUNCHER_PATH", process.execPath);
vi.stubEnv("REA_ANALYSIS_PROVIDER", "environment-provider");
await expect(
runDirectAnalysis(
targetPath,
"binary_overview",
{},
{
providerId: "request-provider",
},
),
).resolves.toMatchObject({
error: "Analysis failed",
code: "capability_unavailable",
details: {
selection_reason: "unknown_provider",
requested_provider_id: "request-provider",
candidate_ids: ["hopper"],
},
});
});
it("replays a cache hit with snapshot read authority only", async () => {
directory = await mkdtemp(join(tmpdir(), "rea-direct-snapshot-"));
const snapshotPath = join(directory, "analysis.json");
const launcherPath = join(directory, "hopper-launcher");
await writeFile(launcherPath, "fixture Hopper launcher");
await chmod(launcherPath, 0o755);
const target = await parseBinaryTarget(process.execPath);
if (!target.ok) throw target.error;
const resolved = await resolveHopperAnalysisProfile(target.value, {
+20
View File
@@ -115,6 +115,26 @@ describe("Hopper analysis profiles", () => {
},
});
});
it("stops launcher hashing when profile resolution is cancelled", async () => {
directory = await mkdtemp(join(tmpdir(), "rea-hopper-profile-cancel-"));
const launcher = join(directory, "hopper");
await writeFile(launcher, "Hopper build");
const controller = new AbortController();
const resolving = resolveHopperAnalysisProfile(target("elf", "x86_64"), {
launcherPath: launcher,
loaderArgsOverride: [],
provider: HOPPER_PROVIDER_IDENTITY,
signal: controller.signal,
});
controller.abort();
await expect(resolving).resolves.toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError", operation: "open_binary" },
});
});
});
const target = (
+92
View File
@@ -0,0 +1,92 @@
import { describe, expect, it } from "vitest";
import { parseConfig } from "../src/config.js";
import type { BinaryTarget } from "../src/domain/binaryTarget.js";
import { HopperProvider } from "../src/hopper/HopperProvider.js";
import { silentLogger } from "../src/logger.js";
describe("Hopper provider discovery", () => {
it("reports bounded launcher availability without starting Hopper", () => {
const available = provider(process.execPath).inspectAvailability();
expect(available).toEqual({
status: "available",
code: null,
reason: null,
diagnostics: {
launcher_path: process.execPath,
platform: process.platform,
},
});
const missingPath = "/missing/rea-hopper-launcher";
expect(provider(missingPath).inspectAvailability()).toEqual({
status: "unavailable",
code: "executable_missing",
reason: `Hopper launcher is missing or not executable: ${missingPath}`,
diagnostics: {
launcher_path: missingPath,
platform: process.platform,
},
});
});
it("separates target kind, format, and architecture support", () => {
const hopper = provider(process.execPath);
expect(hopper.inspectTargetSupport(databaseTarget())).toMatchObject({
status: "supported",
});
expect(
hopper.inspectTargetSupport(executableTarget("elf", "x86_64")),
).toMatchObject({ status: "supported" });
expect(hopper.inspectTargetSupport(artifactTarget())).toMatchObject({
status: "unsupported",
code: "target_kind_unsupported",
diagnostics: { target_kind: "archive", target_format: "asar" },
});
expect(
hopper.inspectTargetSupport(executableTargetWithoutArchitecture()),
).toMatchObject({
status: "unsupported",
code: "architecture_unsupported",
});
});
});
const provider = (launcherPath: string): HopperProvider => {
const config = parseConfig({ HOPPER_LAUNCHER_PATH: launcherPath });
if (!config.ok) throw config.error;
return new HopperProvider(config.value, silentLogger);
};
const databaseTarget = (): BinaryTarget => ({
path: "/tmp/fixture.hop",
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
});
const executableTarget = (
format: "mach-o" | "elf" | "pe",
architecture: "x86" | "x86_64" | "arm" | "arm64",
): BinaryTarget => ({
path: "/tmp/fixture",
sha256: "b".repeat(64),
kind: "executable",
format,
architecture,
availableArchitectures: [architecture],
});
const executableTargetWithoutArchitecture = (): BinaryTarget => ({
path: "/tmp/fixture",
sha256: "b".repeat(64),
kind: "executable",
format: "elf",
});
const artifactTarget = (): BinaryTarget => ({
path: "/tmp/app.asar",
sha256: "c".repeat(64),
kind: "archive",
format: "asar",
});
+4 -1
View File
@@ -15,6 +15,7 @@ describe("configuration parsing integration", () => {
expect(result.value.hopperTargetPath).toBeUndefined();
expect(result.value.hopperTargetKind).toBe("executable");
expect(result.value.hopperLoaderArgs).toEqual([]);
expect(result.value.analysisProvider).toBe("auto");
});
it("parses a complete target-bound configuration", () => {
@@ -22,6 +23,7 @@ describe("configuration parsing integration", () => {
HOPPER_TARGET_PATH: "/usr/bin/true",
HOPPER_TARGET_KIND: "executable",
HOPPER_LOADER_ARGS_JSON: '["-l","Mach-O","--aarch64"]',
REA_ANALYSIS_PROVIDER: "hopper",
REA_EVIDENCE_ROOTS_JSON: '["/tmp/evidence"]',
REA_INVESTIGATION_INPUT_ROOTS_JSON: '["/tmp/releases"]',
REA_ANALYSIS_SNAPSHOT_ROOTS_JSON: '["/tmp/analysis"]',
@@ -30,6 +32,7 @@ describe("configuration parsing integration", () => {
if (!result.ok) throw new Error("unreachable");
expect(result.value.hopperTargetPath).toBe("/usr/bin/true");
expect(result.value.hopperTargetKind).toBe("executable");
expect(result.value.analysisProvider).toBe("hopper");
expect(result.value.hopperLoaderArgs).toEqual([
"-l",
"Mach-O",
@@ -48,7 +51,7 @@ describe("configuration parsing integration", () => {
});
expect(result.ok).toBe(false);
if (result.ok) throw new Error("unreachable");
expect(result.error.message).toContain("Invalid Hopper environment");
expect(result.error.message).toContain("Invalid REA environment");
});
it("rejects invalid JSON in loader arguments", () => {
+16
View File
@@ -27,6 +27,7 @@ import {
import { ensureGeneratedFile } from "../scripts/lib/generated-file.mjs";
import {
createCliInventory,
cliCommandOptionNames,
createProductCatalog,
serializeProductCatalog,
} from "../scripts/lib/product-catalog.mjs";
@@ -101,6 +102,21 @@ describe("canonical product catalog", () => {
]);
});
it("exposes the shared provider selector on every deep-analysis command", () => {
const cli = createCli();
for (const name of [
"analyze",
"inspect",
"decompile",
"xrefs",
"trace",
"function",
"search",
]) {
expect(cliCommandOptionNames(cli, name)).toContain("provider");
}
});
it("reports tool, setup-client, and schema fact drift", async () => {
const catalog = await createProductCatalog(root);
const drifted = {
+356
View File
@@ -0,0 +1,356 @@
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { z } from "zod";
import {
createAnalysisExecution,
type AnalysisClient,
type AnalysisProvider,
type AnalysisProviderCandidate,
type CapabilityDescriptor,
type ProviderIdentity,
} from "../src/application/AnalysisProvider.js";
import { AnalysisProviderRegistry } from "../src/application/AnalysisProviderRegistry.js";
import { BinarySession } from "../src/application/BinarySession.js";
import { SessionProviderRouter } from "../src/application/SessionProviderRouter.js";
import { createAnalysisProfile } from "../src/domain/analysisProfile.js";
import {
AnalysisCancelledError,
ProviderAdapterError,
} from "../src/domain/errors.js";
import { err, ok } from "../src/domain/result.js";
let directory: string | undefined;
afterEach(async () => {
if (directory !== undefined)
await rm(directory, { recursive: true, force: true });
directory = undefined;
});
describe("target-bound provider routing", () => {
it("rejects provider identity and operation-family collisions at composition", () => {
const alpha = deepProvider("alpha");
const registry = new AnalysisProviderRegistry([alpha.provider]);
expect(() =>
SessionProviderRouter.selectable(registry, [auxiliaryProvider("alpha")]),
).toThrow(/Duplicate configured provider ID: alpha/u);
expect(() =>
SessionProviderRouter.selectable(registry, [
auxiliaryProvider("auxiliary", "address_name"),
]),
).toThrow(
/Deep and auxiliary providers both declare operation address_name/u,
);
});
it("binds one overlapping provider, preserves provenance, and never falls back", async () => {
const target = await databaseTarget();
const alpha = deepProvider("alpha");
const beta = deepProvider("beta");
const auxiliary = auxiliaryProvider();
const session = selectableSession(
[beta.provider, alpha.provider],
auxiliary,
);
const ambiguous = await session.open(target);
expect(ambiguous.ok).toBe(false);
if (!ambiguous.ok)
expect(ambiguous.error).toMatchObject({ reason: "ambiguous" });
expect(alpha.clients).toHaveLength(0);
expect(beta.clients).toHaveLength(0);
expect(session.activeTarget()).toBeUndefined();
expect((await session.open(target, { providerId: "alpha" })).ok).toBe(true);
expect(bindingStatus(session)).toMatchObject({
analysis_provider_binding: {
provider: { id: "alpha", version: "1" },
selection_source: "request",
},
analysis_provider_candidates: [
{ provider: { id: "alpha" }, selected: true },
{ provider: { id: "beta" }, selected: false },
],
});
expect(alpha.clients).toHaveLength(0);
const observed = await session.execute("address_name", { address: "0x1" });
expect(observed.ok).toBe(true);
if (observed.ok)
expect(observed.value).toMatchObject({
provider: { id: "alpha", version: "1" },
analysisProfile: { provider: { id: "alpha", version: "1" } },
result: "alpha:address_name",
});
expect(alpha.clients).toHaveLength(1);
expect(beta.clients).toHaveLength(0);
expect((await session.open(target, { providerId: "alpha" })).ok).toBe(true);
expect(alpha.clients).toHaveLength(1);
expect(alpha.clients[0]?.closed).toBe(false);
const auxiliaryResult = await session.execute("inspect_macho", {});
expect(auxiliaryResult.ok && auxiliaryResult.value.provider.id).toBe(
"auxiliary",
);
alpha.available = false;
expect((await session.open(target)).ok).toBe(true);
expect(bindingStatus(session)).toMatchObject({
analysis_provider_binding: { provider: { id: "alpha" } },
});
const unknown = await session.open(target, { providerId: "missing" });
expect(unknown.ok).toBe(false);
if (!unknown.ok)
expect(unknown.error).toMatchObject({ reason: "unknown_provider" });
expect(bindingStatus(session)).toMatchObject({
analysis_provider_binding: { provider: { id: "alpha" } },
});
expect((await session.open(target, { providerId: "beta" })).ok).toBe(true);
expect(alpha.clients[0]?.closed).toBe(true);
beta.fail = true;
const failed = await session.execute("address_name", { address: "0x2" });
expect(failed.ok).toBe(false);
if (!failed.ok) expect(failed.error._tag).toBe("ProviderAdapterError");
expect(alpha.clients[0]?.calls).toEqual(["address_name"]);
expect(bindingStatus(session)).toMatchObject({
analysis_provider_binding: { provider: { id: "beta" } },
});
await session.close();
expect(beta.clients[0]?.closed).toBe(true);
});
it("cancels a provider switch, closes its old client, and restores the binding", async () => {
const target = await databaseTarget();
const alpha = deepProvider("alpha");
const beta = deepProvider("beta");
const pending = deferred<ReturnType<typeof successfulExecution>>();
alpha.pending = pending.promise;
const session = selectableSession([alpha.provider, beta.provider]);
expect((await session.open(target, { providerId: "alpha" })).ok).toBe(true);
const running = session.execute("address_name", { address: "0x1" });
await new Promise<void>((resolve) => setImmediate(resolve));
const controller = new AbortController();
const switching = session.open(target, {
providerId: "beta",
signal: controller.signal,
});
while (beta.profileResolutions === 0)
await new Promise<void>((resolve) => setImmediate(resolve));
controller.abort();
pending.resolve(successfulExecution("alpha"));
expect(await running).toMatchObject({ ok: true });
const cancelled = await switching;
expect(cancelled).toEqual({
ok: false,
error: new AnalysisCancelledError("open_binary"),
});
expect(alpha.clients[0]?.closed).toBe(true);
expect(beta.clients).toHaveLength(0);
expect(bindingStatus(session)).toMatchObject({
analysis_provider_binding: { provider: { id: "alpha" } },
});
alpha.pending = undefined;
const restored = await session.execute("address_name", { address: "0x2" });
expect(restored.ok && restored.value.provider.id).toBe("alpha");
expect(alpha.clients).toHaveLength(2);
await session.close();
expect(alpha.clients[1]?.closed).toBe(true);
});
});
interface ClientState {
readonly calls: string[];
closed: boolean;
}
interface DeepProviderFixture {
provider: AnalysisProviderCandidate;
readonly clients: ClientState[];
available: boolean;
fail: boolean;
profileResolutions: number;
pending: Promise<ReturnType<typeof successfulExecution>> | undefined;
}
const deepProvider = (id: string): DeepProviderFixture => {
const identity: ProviderIdentity = {
id,
name: `${id} provider`,
version: null,
};
const fixture: Omit<DeepProviderFixture, "provider"> = {
clients: [],
available: true,
fail: false,
profileResolutions: 0,
pending: undefined,
};
const provider: AnalysisProviderCandidate = {
identity: () => identity,
capabilities: () => [capability(identity, "address_name")],
inspectAvailability: () =>
fixture.available
? {
status: "available",
code: null,
reason: null,
diagnostics: { executable_path: `/opt/${id}/bin/analyze` },
}
: {
status: "unavailable",
code: "runtime_missing",
reason: `${id} runtime is unavailable`,
diagnostics: { executable_path: `/opt/${id}/bin/analyze` },
},
inspectTargetSupport: () => ({
status: "supported",
code: null,
reason: null,
diagnostics: {},
}),
resolveAnalysisProfile: () => {
fixture.profileResolutions += 1;
return Promise.resolve(
ok({
profile: createAnalysisProfile(
{ id, name: identity.name, version: "1" },
1,
{ provider: id },
),
compatibility: {},
}),
);
},
createClient: (_target, profile): AnalysisClient => {
const state: ClientState = { calls: [], closed: false };
fixture.clients.push(state);
return {
execute: (operation) => {
state.calls.push(operation);
if (fixture.fail)
return Promise.resolve(
err(new ProviderAdapterError(id, operation)),
);
if (fixture.pending !== undefined) return fixture.pending;
return Promise.resolve(successfulExecution(id, profile?.provider));
},
close: () => {
state.closed = true;
return Promise.resolve();
},
};
},
};
return Object.assign(fixture, { provider });
};
const successfulExecution = (
id: string,
provider: ProviderIdentity = {
id,
name: `${id} provider`,
version: "1",
},
) => ok(createAnalysisExecution(`${id}:address_name`, provider));
const auxiliaryProvider = (
id = "auxiliary",
operation: "address_name" | "inspect_macho" = "inspect_macho",
): AnalysisProvider => {
const identity = {
id,
name: `${id} provider`,
version: "1",
};
return {
identity: () => identity,
capabilities: () => [capability(identity, operation)],
createClient: () => ({
execute: (operation) =>
Promise.resolve(
ok(createAnalysisExecution(`${operation}:auxiliary`, identity)),
),
close: () => Promise.resolve(),
}),
};
};
const selectableSession = (
providers: readonly AnalysisProviderCandidate[],
auxiliary?: AnalysisProvider,
): BinarySession =>
new BinarySession(
SessionProviderRouter.selectable(
new AnalysisProviderRegistry(providers),
auxiliary === undefined ? [] : [auxiliary],
),
);
const capability = (
provider: ProviderIdentity,
operation: "address_name" | "inspect_macho",
): CapabilityDescriptor => ({
provider,
operation,
inputContractVersion: 1,
outputContractVersion: 1,
available: true,
reason: null,
pagination: "none",
exhaustive: true,
effects: {
mutatesArtifact: false,
launchesProcess: operation === "address_name",
mayShowUi: false,
mayAccessNetwork: false,
mayWriteFilesystem: false,
changesPermissions: false,
requiresRoot: false,
},
limits: { maxResults: null, maxPayloadBytes: 1_000, timeoutMs: 1_000 },
limitations: [],
});
const databaseTarget = async (): Promise<string> => {
directory = await mkdtemp(join(tmpdir(), "rea-provider-binding-"));
const path = join(directory, "fixture.hop");
await writeFile(path, "fixture");
return path;
};
const bindingStatus = (session: BinarySession) =>
z
.object({
analysis_provider_binding: z.unknown(),
analysis_provider_candidates: z.array(z.unknown()),
})
.passthrough()
.parse(session.status());
interface Deferred<Value> {
readonly promise: Promise<Value>;
resolve(value: Value): void;
}
const deferred = <Value>(): Deferred<Value> => {
let resolvePromise: ((value: Value) => void) | undefined;
const promise = new Promise<Value>((resolve) => {
resolvePromise = resolve;
});
return {
promise,
resolve(value) {
resolvePromise?.(value);
},
};
};
+225
View File
@@ -0,0 +1,225 @@
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
import type { CallToolResult } from "@modelcontextprotocol/server";
import { afterEach, describe, expect, it } from "vitest";
import { z } from "zod";
import {
createAnalysisExecution,
type AnalysisProviderCandidate,
type CapabilityDescriptor,
type ProviderIdentity,
} from "../src/application/AnalysisProvider.js";
import { AnalysisProviderRegistry } from "../src/application/AnalysisProviderRegistry.js";
import { BinarySession } from "../src/application/BinarySession.js";
import { SessionProviderRouter } from "../src/application/SessionProviderRouter.js";
import { createAnalysisProfile } from "../src/domain/analysisProfile.js";
import { ok } from "../src/domain/result.js";
import { silentLogger } from "../src/logger.js";
import { createServer } from "../src/server/createServer.js";
const resources: Array<{ close(): Promise<unknown> }> = [];
let directory: string | undefined;
afterEach(async () => {
await Promise.all(resources.splice(0).map((resource) => resource.close()));
if (directory !== undefined)
await rm(directory, { recursive: true, force: true });
directory = undefined;
});
describe("provider selection over MCP", () => {
it("keeps open_binary and binary_session binding semantics exact", async () => {
directory = await mkdtemp(join(tmpdir(), "rea-provider-mcp-"));
const target = join(directory, "fixture.hop");
await writeFile(target, "fixture");
const starts: string[] = [];
const session = new BinarySession(
SessionProviderRouter.selectable(
new AnalysisProviderRegistry([
candidate("beta", starts),
candidate("alpha", starts),
]),
[],
),
);
const server = createServer(session, session, { logger: silentLogger });
const mcp = new Client({ name: "provider-selection", version: "1.0.0" });
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
resources.push(mcp, server);
await server.connect(serverTransport);
await mcp.connect(clientTransport);
const before = structured(
await mcp.callTool({ name: "binary_session", arguments: {} }),
);
expect(before.result).toMatchObject({
open: false,
analysis_provider_binding: null,
analysis_provider_candidates: [
{
provider: { id: "alpha" },
target_support: { status: "unknown" },
selected: false,
},
{
provider: { id: "beta" },
target_support: { status: "unknown" },
selected: false,
},
],
});
expect(starts).toEqual([]);
const malformed = await mcp.callTool({
name: "open_binary",
arguments: { path: target, provider_id: "Beta" },
});
expect(malformed.isError).toBe(true);
expect(starts).toEqual([]);
const ambiguous = await mcp.callTool({
name: "open_binary",
arguments: { path: target },
});
expect(ambiguous.isError).toBe(true);
expect(structured(ambiguous)).toMatchObject({
error: {
code: "capability_unavailable",
details: {
selection_reason: "ambiguous",
requested_provider_id: "auto",
candidate_ids: ["alpha", "beta"],
},
},
});
expect(starts).toEqual([]);
const opened = await mcp.callTool({
name: "open_binary",
arguments: { path: target, provider_id: "beta" },
});
expect(opened.isError).not.toBe(true);
expect(starts).toEqual([]);
const observed = await mcp.callTool({
name: "address_name",
arguments: {},
});
expect(observed.isError).not.toBe(true);
expect(structured(observed)).toMatchObject({
provider: { id: "beta", version: "1" },
analysis_profile: { provider: { id: "beta", version: "1" } },
normalized_result: "beta:address_name",
});
expect(starts).toEqual(["beta"]);
const status = structured(
await mcp.callTool({ name: "binary_session", arguments: {} }),
);
expect(status.result).toMatchObject({
open: true,
analysis_provider_binding: {
provider: { id: "beta", version: "1" },
selection_source: "request",
},
analysis_provider_candidates: [
{ provider: { id: "alpha" }, selected: false },
{ provider: { id: "beta", version: "1" }, selected: true },
],
});
const unknown = await mcp.callTool({
name: "open_binary",
arguments: { path: target, provider_id: "missing" },
});
expect(unknown.isError).toBe(true);
expect(structured(unknown)).toMatchObject({
error: { details: { selection_reason: "unknown_provider" } },
});
expect(
structured(await mcp.callTool({ name: "binary_session", arguments: {} }))
.result,
).toMatchObject({
analysis_provider_binding: { provider: { id: "beta" } },
});
});
});
const candidate = (id: string, starts: string[]): AnalysisProviderCandidate => {
const identity: ProviderIdentity = {
id,
name: `${id} provider`,
version: null,
};
return {
identity: () => identity,
capabilities: () => [capability(identity)],
inspectAvailability: () => ({
status: "available",
code: null,
reason: null,
diagnostics: { executable_path: `/opt/${id}/bin/analyze` },
}),
inspectTargetSupport: () => ({
status: "supported",
code: null,
reason: null,
diagnostics: {},
}),
resolveAnalysisProfile: () =>
Promise.resolve(
ok({
profile: createAnalysisProfile(
{ id, name: identity.name, version: "1" },
1,
{ fixture: id },
),
compatibility: {},
}),
),
createClient: (_target, profile) => {
starts.push(id);
return {
execute: (operation) =>
Promise.resolve(
ok(
createAnalysisExecution(
`${id}:${operation}`,
profile?.provider ?? identity,
),
),
),
close: () => Promise.resolve(),
};
},
};
};
const capability = (provider: ProviderIdentity): CapabilityDescriptor => ({
provider,
operation: "address_name",
inputContractVersion: 1,
outputContractVersion: 1,
available: true,
reason: null,
pagination: "none",
exhaustive: true,
effects: {
mutatesArtifact: false,
launchesProcess: true,
mayShowUi: false,
mayAccessNetwork: false,
mayWriteFilesystem: false,
changesPermissions: false,
requiresRoot: false,
},
limits: { maxResults: null, maxPayloadBytes: 1_000, timeoutMs: 1_000 },
limitations: [],
});
const structured = (result: CallToolResult): Record<string, unknown> =>
z.record(z.string(), z.unknown()).parse(result.structuredContent);