diff --git a/docs/reverse-engineering-tools.md b/docs/reverse-engineering-tools.md index 01ec8ced8e..f2a880afa2 100644 --- a/docs/reverse-engineering-tools.md +++ b/docs/reverse-engineering-tools.md @@ -271,6 +271,40 @@ they use `%LOCALAPPDATA%\REA\CutterBridge` on Windows when `LOCALAPPDATA` is set and `~/.cache/rea/cutter-bridge` otherwise. The two processes must resolve the same directory for discovery to find the published sessions. +REA's npm package includes the plugin as `bridge/cutter/rea_bridge.py`. Use the +copy from the REA version you run (`rea --version`, or the version in an +`npx rea-agents@` registration). An `npx` installation keeps that +package in npm's cache rather than a stable folder, so take the file from the +published package of the same version instead (in Windows PowerShell, use +`npm.cmd`): + +```sh +npm pack rea-agents@ +tar -xzf rea-agents-.tgz package/bridge/cutter/rea_bridge.py +``` + +Copy the extracted `package/bridge/cutter/rea_bridge.py` into the `python` +subdirectory of Cutter's plugin directory, then restart Cutter. Cutter shows that +directory and the loaded plugins under Edit > Preferences > Plugins. When no +session in the bridge directory answers, `list_cutter_sessions` reports +`no_live_bridge_found` with a limitation that names the possible causes. Whether +or not a session answers, it also counts descriptor files it could not read, +without claiming they belong to a session, and published sessions that did not +answer, because neither is listed. If Cutter lists the plugin as loaded but +discovery still finds no session, check that the bridge directory is writable +and has free space: the bridge does not log a failure to publish its session. + +Official Cutter 2.5.0 builds have been observed to reject Python plugins at +startup: Cutter's own sample plugin in the Linux AppImage, and this bridge and a +minimal independent plugin on macOS arm64 +([rizinorg/cutter#3659](https://github.com/rizinorg/cutter/issues/3659)). The +log then shows `Plugin's create_cutter_plugin() function did not return an +instance of CutterPlugin` and `Loaded 0 plugin(s)`, and no session is +published. Because a minimal plugin fails the same way, a change to REA's +bridge is not expected to help; the cause is unconfirmed upstream. Cutter 2.4.1 +loaded the bridge on the same macOS arm64 host, where discovery and an `ij` +command worked. Other hosts and Cutter builds have not been checked. + The plugin publishes the SHA-256 of its own file on its session descriptor. Discovery reports each session's `bridge_source`: `packaged` when it matches REA's packaged `bridge/cutter/rea_bridge.py`, `modified` when it differs, and diff --git a/scripts/verify/advertised-schemas/tools/list_cutter_sessions.json b/scripts/verify/advertised-schemas/tools/list_cutter_sessions.json index d12f571d2f..a876e1fbc5 100644 --- a/scripts/verify/advertised-schemas/tools/list_cutter_sessions.json +++ b/scripts/verify/advertised-schemas/tools/list_cutter_sessions.json @@ -1,7 +1,7 @@ { "schemas": { "input compact": "32062bdb9024160d", - "output compact": "a61f3d77d190e70d" + "output compact": "a80524bc8752a453" }, "patterns": { "output": [ diff --git a/src/cutter/CutterBridgeClient.ts b/src/cutter/CutterBridgeClient.ts index afd4d6118e..9c02606b76 100644 --- a/src/cutter/CutterBridgeClient.ts +++ b/src/cutter/CutterBridgeClient.ts @@ -41,6 +41,7 @@ import type { import { jsonValueByteLength } from "../domain/jsonValueByteLength.js"; import type { JsonValue } from "../domain/jsonValue.js"; import { + cutterDiscoveryLimitations, cutterSessionSchema, type CutterBridgeDiscovery, type CutterBridgeSession, @@ -384,10 +385,9 @@ export class CutterBridgeClient { } } - async listSessions( - options: CutterDiscoveryOptions = {}, - ): Promise { - const { signal } = options; + async listSessions({ + signal, + }: CutterDiscoveryOptions = {}): Promise { assertBridgeActive(signal, "list_cutter_sessions"); this.#requestLimit(); const mismatches: number[] = []; @@ -398,6 +398,7 @@ export class CutterBridgeClient { bridge_directory: this.#directory, discovery_status: loaded.error, bridge_directory_security: loaded.security, + limitations: cutterDiscoveryLimitations(loaded.error), }; const descriptors = await mapDiscovery( loaded.descriptors, @@ -488,12 +489,17 @@ export class CutterBridgeClient { "Cutter", "No status request was sent to the mismatched session.", ); + const discoveryStatus = + sessions.length > 0 ? "sessions_found" : "no_live_bridge_found"; return { sessions, bridge_directory: this.#directory, - discovery_status: - sessions.length > 0 ? "sessions_found" : "no_live_bridge_found", + discovery_status: discoveryStatus, bridge_directory_security: loaded.security, + limitations: cutterDiscoveryLimitations(discoveryStatus, { + unreadable: loaded.unreadable, + unanswered: descriptors.length - sessions.length, + }), }; } @@ -867,18 +873,28 @@ export class CutterBridgeClient { } } - async #loadDescriptors(signal: AbortSignal | undefined): Promise<{ - readonly descriptors: readonly z.infer[]; - readonly security: - | "private_verified" - | "not_private" - | "unverified_platform_acl" - | "not_checked"; - readonly error?: - | "bridge_directory_unavailable" - | "bridge_directory_insecure" - | "bridge_directory_capacity_exceeded"; - }> { + async #loadDescriptors(signal: AbortSignal | undefined): Promise< + { + readonly descriptors: readonly z.infer[]; + readonly security: + | "private_verified" + | "not_private" + | "unverified_platform_acl" + | "not_checked"; + } & ( + | { + readonly error?: undefined; + /** Filename-matching candidates that could not be read as a descriptor. */ + readonly unreadable: number; + } + | { + readonly error: + | "bridge_directory_unavailable" + | "bridge_directory_insecure" + | "bridge_directory_capacity_exceeded"; + } + ) + > { assertArtifactReadActive(signal); let directoryInfo; try { @@ -886,7 +902,7 @@ export class CutterBridgeClient { } catch (cause) { const code = (cause as NodeJS.ErrnoException).code; if (code === "ENOENT") - return { descriptors: [], security: "not_checked" }; + return { descriptors: [], security: "not_checked", unreadable: 0 }; return { descriptors: [], security: "not_checked", @@ -1027,12 +1043,13 @@ export class CutterBridgeClient { () => assertArtifactReadActive(signal), ); assertArtifactReadActive(signal); + const descriptors = loaded.filter( + (value): value is z.infer => value !== undefined, + ); return { - descriptors: loaded.filter( - (value): value is z.infer => - value !== undefined, - ), + descriptors, security, + unreadable: entries.length - descriptors.length, }; } diff --git a/src/domain/cutterDiscovery.ts b/src/domain/cutterDiscovery.ts index 026b007e0f..8a039bee9f 100644 --- a/src/domain/cutterDiscovery.ts +++ b/src/domain/cutterDiscovery.ts @@ -44,8 +44,60 @@ export const cutterDiscoverySchema = z.strictObject({ "unverified_platform_acl", "not_checked", ]), + /** What this discovery status cannot establish. */ + limitations: z.array(z.string()), }); +/** Descriptor candidates in bridge_directory that discovery examined but could not list. */ +export type CutterUnlistedDescriptors = { + /** + * Filename-matching candidates that could not be read as a descriptor. They + * do not establish that any session exists. + */ + readonly unreadable: number; + /** Readable descriptors whose session did not return a valid status. */ + readonly unanswered: number; +}; + +/** + * When no session answers, discovery cannot tell why no live session was + * published, so the limitation lists the possible causes and the observed + * Cutter 2.5.0 plugin rejection. Unreadable descriptor candidates and + * unanswered sessions are counted separately. + */ +const NO_LIVE_BRIDGE_LIMITATION = + "No REA bridge session in bridge_directory answered. Discovery cannot tell whether Cutter is not running, did not load the REA Python plugin, loaded it but could not publish a session (for example, an unwritable or full bridge directory), or uses another REA_CUTTER_BRIDGE_DIR. Cutter's startup log shows whether the plugin loaded; the bridge does not log a publication failure. Official Cutter 2.5.0 builds have been observed to reject Python plugins, including this one (rizinorg/cutter#3659)."; + +const unlistedLimitations = ({ + unreadable, + unanswered, +}: CutterUnlistedDescriptors): string[] => [ + ...(unreadable === 0 + ? [] + : [ + `${String(unreadable)} descriptor ${unreadable === 1 ? "candidate" : "candidates"} in bridge_directory could not be read (removed, not a private regular file, unreadable, oversized, malformed, or not matching its file name). Whether ${unreadable === 1 ? "it describes a Cutter session" : "they describe Cutter sessions"} is unknown.`, + ]), + ...(unanswered === 0 + ? [] + : [ + `${String(unanswered)} published ${unanswered === 1 ? "session" : "sessions"} in bridge_directory did not return a valid status (stale after Cutter exited, unresponsive, or an incompatible bridge version) and ${unanswered === 1 ? "is" : "are"} not listed.`, + ]), +]; + +/** + * Limitations owned by each discovery status. A found session does not make + * discovery complete: unreadable descriptor candidates and sessions whose + * status probe failed stay unlisted, and their counts remain visible. + */ +export const cutterDiscoveryLimitations = ( + status: z.infer["discovery_status"], + unlisted: CutterUnlistedDescriptors = { unreadable: 0, unanswered: 0 }, +): string[] => { + if (status === "no_live_bridge_found") + return [NO_LIVE_BRIDGE_LIMITATION, ...unlistedLimitations(unlisted)]; + return status === "sessions_found" ? unlistedLimitations(unlisted) : []; +}; + export type CutterBridgeSession = z.infer; export type CutterBridgeDiscovery = Readonly< diff --git a/tests/boundary/cli/cutterCommands.test.ts b/tests/boundary/cli/cutterCommands.test.ts index 38fdd7503e..7db9c0d5ae 100644 --- a/tests/boundary/cli/cutterCommands.test.ts +++ b/tests/boundary/cli/cutterCommands.test.ts @@ -7,6 +7,7 @@ import { join } from "node:path"; import { afterEach, describe, expect, it } from "vitest"; import { serveCli } from "./cliServeHarness.js"; +import { cutterDiscoveryLimitations } from "../../../src/domain/cutterDiscovery.js"; import { spawnOwnedProviderProcess, ProviderProcessSupervisor, @@ -44,10 +45,14 @@ describe("Cutter CLI commands", () => { }); expect(result.exitCode).toBe(0); + // The CLI projects the shared discovery owner's limitation unchanged. + const limitations = cutterDiscoveryLimitations("no_live_bridge_found"); + expect(limitations).not.toEqual([]); expect(JSON.parse(result.stdout)).toMatchObject({ sessions: [], discovery_status: "no_live_bridge_found", bridge_directory: directory, + limitations, }); }); diff --git a/tests/boundary/mcp/cutterCancellationMcp.test.ts b/tests/boundary/mcp/cutterCancellationMcp.test.ts index 8391a1e76c..8fede3bc87 100644 --- a/tests/boundary/mcp/cutterCancellationMcp.test.ts +++ b/tests/boundary/mcp/cutterCancellationMcp.test.ts @@ -12,6 +12,7 @@ import { import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { CutterBridgeClient } from "../../../src/cutter/CutterBridgeClient.js"; import { CutterBridgeService } from "../../../src/cutter/CutterBridgeService.js"; +import { cutterDiscoveryLimitations } from "../../../src/domain/cutterDiscovery.js"; import { toolContract } from "../../../src/contracts/toolContracts.js"; import { cutterMcpServer } from "../../fixtures/debuggerMcp.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; @@ -29,6 +30,7 @@ it("propagates MCP cancellation into an active Cutter command", async () => { bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), execute: async ({ signal }) => { dispatch.arrive(); @@ -99,6 +101,7 @@ it("shares one cleanup proof across concurrent Cutter MCP commands without Binar bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), confirmCommandCompletion: async () => { confirmations += 1; @@ -259,6 +262,7 @@ it("cancels active discovery sockets, stops queued probes and recovers on the sa ...(process.platform === "win32" ? {} : { bridge_directory_security: "private_verified" }), + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }); expect(connections).toBe(8); } finally { diff --git a/tests/boundary/mcp/cutterMcp.test.ts b/tests/boundary/mcp/cutterMcp.test.ts index 7b16e99abd..3b5af46c7f 100644 --- a/tests/boundary/mcp/cutterMcp.test.ts +++ b/tests/boundary/mcp/cutterMcp.test.ts @@ -245,6 +245,7 @@ it("preserves live Cutter command Evidence and parity through the MCP boundary", expect(discovery.structuredContent).toMatchObject({ discovery_status: "sessions_found", sessions: [{ session_id: sessionId, document_generation: 3 }], + limitations: [], }); const command = await client.callTool({ diff --git a/tests/boundary/providers/CutterBridgeClient.test.ts b/tests/boundary/providers/CutterBridgeClient.test.ts index bf993da6ab..2f735ce581 100644 --- a/tests/boundary/providers/CutterBridgeClient.test.ts +++ b/tests/boundary/providers/CutterBridgeClient.test.ts @@ -23,6 +23,7 @@ import { afterEach, describe, expect, it, vi } from "vitest"; import { CutterBridgeClient } from "../../../src/cutter/CutterBridgeClient.js"; import { AnalysisInputError } from "../../../src/domain/analysisErrorCore.js"; import { CutterBridgeService } from "../../../src/cutter/CutterBridgeService.js"; +import { cutterDiscoveryLimitations } from "../../../src/domain/cutterDiscovery.js"; const listen = async ( server: ReturnType, @@ -700,10 +701,15 @@ describe("CutterBridgeClient: scenario group 2", () => { ).toBe(0o600); } } + // Each skipped candidate stays counted beside the found session. const result = await client.listSessions(); expect(result).toMatchObject({ discovery_status: "sessions_found", sessions: [{ session_id: sessionId }], + limitations: cutterDiscoveryLimitations("sessions_found", { + unreadable: 3, + unanswered: 0, + }), }); expect(connections).toBe(1); }); @@ -720,11 +726,17 @@ describe("CutterBridgeClient: scenario group 2", () => { port, "synthetic-cutter-bridge-token-for-test", ); + // A published session whose status probe fails is a no-live discovery + // that counts the unanswered session. await expect( createClient({ REA_CUTTER_BRIDGE_DIR: directory }).listSessions(), ).resolves.toMatchObject({ discovery_status: "no_live_bridge_found", sessions: [], + limitations: cutterDiscoveryLimitations("no_live_bridge_found", { + unreadable: 0, + unanswered: 1, + }), }); }); }); @@ -1593,6 +1605,7 @@ describe("CutterBridgeClient: scenario group 9", () => { bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found" as const, bridge_directory_security: "private_verified" as const, + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }; const service = new CutterBridgeService({ listSessions: async () => discovery, @@ -1680,6 +1693,7 @@ describe("CutterBridgeClient: scenario group 9", () => { bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), execute: async () => ({ requestId: "4b18ce4d-bf31-456e-ae31-e8c547b2f9db", diff --git a/tests/boundary/providers/CutterBridgeService.test.ts b/tests/boundary/providers/CutterBridgeService.test.ts index 47eae582e2..a8a531d5a6 100644 --- a/tests/boundary/providers/CutterBridgeService.test.ts +++ b/tests/boundary/providers/CutterBridgeService.test.ts @@ -1,6 +1,7 @@ import { expect, it, vi } from "vitest"; import { CutterBridgeService } from "../../../src/cutter/CutterBridgeService.js"; +import { cutterDiscoveryLimitations } from "../../../src/domain/cutterDiscovery.js"; import { AnalysisInputError, AnalysisCancelledError, @@ -43,6 +44,7 @@ it.each(["descriptor-first", "command-first"] as const)( bridge_directory: "/fixture", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), confirmCommandCompletion: async () => readFails @@ -108,6 +110,7 @@ it("retains uncertain command completion as Evidence without encouraging a retry bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), execute: async () => ({ requestId: "4b18ce4d-bf31-456e-ae31-e8c547b2f9db", @@ -180,6 +183,7 @@ it("clears a poisoned command only after its exact UI-dispatcher receipt", async bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), confirmCommandCompletion, execute: async () => { @@ -313,6 +317,7 @@ it("recovers canceled command A after B and does not retain poisoned B", async ( bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found" as const, bridge_directory_security: "private_verified" as const, + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), confirmCommandCompletion, execute, @@ -352,6 +357,7 @@ it("rejects malformed Cutter commands and pre-aborted calls", async () => { bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), execute: async () => { throw new Error("must not dispatch"); @@ -385,6 +391,7 @@ it.each([ bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), execute: async () => { throw failure; @@ -406,6 +413,7 @@ it.each(["transport cancelled", "command may have completed"])( bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), execute: async () => { controller.abort(new Error("later cancellation")); @@ -446,6 +454,7 @@ it("shares one cleanup attempt when commands retry the same receipt together", a bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), confirmCommandCompletion, execute: async () => { @@ -530,6 +539,7 @@ it.each([ bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }; }, execute: async () => { @@ -571,6 +581,7 @@ it.each(["descriptor-first", "command-first"])( bridge_directory: "/fixture", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), confirmCommandCompletion: async () => ({ ok: true, value: terminal }), retryDescriptorCleanup: releaseDescriptors, @@ -619,6 +630,7 @@ it.each([ bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), execute: async () => { throw cause; @@ -648,6 +660,7 @@ it.each([ bridge_directory: "/private/bridge", discovery_status: "no_live_bridge_found", bridge_directory_security: "private_verified", + limitations: cutterDiscoveryLimitations("no_live_bridge_found"), }), execute: async () => { controller.abort(reason); diff --git a/tests/boundary/providers/cutterBridgeRequestLimit.test.ts b/tests/boundary/providers/cutterBridgeRequestLimit.test.ts index f9d5ee340a..dc8b86214d 100644 --- a/tests/boundary/providers/cutterBridgeRequestLimit.test.ts +++ b/tests/boundary/providers/cutterBridgeRequestLimit.test.ts @@ -9,6 +9,7 @@ import { expect, it, onTestFinished, vi } from "vitest"; import { CutterBridgeClient } from "../../../src/cutter/CutterBridgeClient.js"; import { runWithAnalysisOperationSnapshot } from "../../../src/domain/analysisOperationSnapshot.js"; import { CutterBridgeService } from "../../../src/cutter/CutterBridgeService.js"; +import { cutterDiscoveryLimitations } from "../../../src/domain/cutterDiscovery.js"; import { ConfigurationError } from "../../../src/domain/configurationErrors.js"; import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js"; import { @@ -262,9 +263,16 @@ it("returns the matching session when the other ceiling descriptor is stale", as }); await writeDescriptor(directory, other, await closedPort(), TOKEN); const client = clientFor(directory, "8192"); + // The stale session's failed probe stays visible beside the found session. + const limitations = cutterDiscoveryLimitations("sessions_found", { + unreadable: 0, + unanswered: 1, + }); + expect(limitations).not.toEqual([]); await expect(client.listSessions()).resolves.toMatchObject({ discovery_status: "sessions_found", sessions: [{ session_id: SESSION }], + limitations, }); }); diff --git a/tests/process-global/commandFinalizationCancellation.test.ts b/tests/process-global/commandFinalizationCancellation.test.ts index 507659323e..02b3689396 100644 --- a/tests/process-global/commandFinalizationCancellation.test.ts +++ b/tests/process-global/commandFinalizationCancellation.test.ts @@ -15,6 +15,7 @@ import { analysisErrorProjectionSchema } from "../../src/domain/analysisErrorPro import { toolContract } from "../../src/contracts/toolContracts.js"; import { CutterBridgeService } from "../../src/cutter/CutterBridgeService.js"; import { AnalysisOutputError } from "../../src/domain/analysisErrorCore.js"; +import { cutterDiscoveryLimitations } from "../../src/domain/cutterDiscovery.js"; import * as analysisView from "../../src/domain/analysisView/analysisView.js"; import { parseEvidence } from "../../src/domain/evidence.js"; import { createEvidenceBundle } from "../../src/domain/evidenceBundle.js"; @@ -88,6 +89,7 @@ const cutterDiscoveryFixture = () => bridge_directory: "/caller/Cutter bridge/token=literal%2F/证据", discovery_status: "sessions_found", bridge_directory_security: "unverified_platform_acl", + limitations: cutterDiscoveryLimitations("sessions_found"), }); const finalCloseGate = () => {