Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(cutter): attribute status proof failures to command
morluto5c0472c571cd
diff --git a/docs/reverse-engineering-tools.md b/docs/reverse-engineering-tools.mdindex 3373526c9..bb5df5ef3 100644--- a/docs/reverse-engineering-tools.md+++ b/docs/reverse-engineering-tools.md@@ -73,7 +73,9 @@ invocation. A signed status response also confirms completion of older bridgeconnections after its UI dispatch, preserving recovery proof for a caller whosereceipt another caller has acknowledged. Neither receipt recovery nor a statusprobe retries the original command. Failed acknowledgements remain pending and-block new commands until they can be retried successfully.+block new commands until they can be retried successfully. Status proof failures+identify `cutter_command` and retain `status` in+`details.diagnostics.auxiliary_operation`; malformed proof still blocks dispatch.## Configuration and coveragediff --git a/src/cutter/CutterBridgeClient.ts b/src/cutter/CutterBridgeClient.tsindex dc821745d..8ca252510 100644--- a/src/cutter/CutterBridgeClient.ts+++ b/src/cutter/CutterBridgeClient.ts@@ -530,52 +530,34 @@ export class CutterBridgeClient {);}try {- const raw = await this.#request(- descriptor,- serializeRequest(descriptor, {- kind: "status",- session_id: sessionId,- }),- );- const parsed = responseSchema.safeParse(raw);- if (- !parsed.success ||- !parsed.data.ok ||- parsed.data.session_id !== sessionId- )- return err(- new AnalysisOutputError(- "cutter_command_status",- "The bridge status response did not contain a valid session identity.",- { cause: parsed.success ? undefined : parsed.error },- ),- );- const completed = (parsed.data.completed_commands ?? []).some(+ const status = await this.#readCommandStatus(descriptor);+ const completed = (status.completed_commands ?? []).some((receipt) => receipt.request_id === requestId,);if (completed) await this.#acknowledgeCompletion(descriptor, requestId);return ok(completed ||(completionToken !== undefined &&- parsed.data.completed_connection !== undefined &&- parsed.data.completed_connection >= completionToken),+ status.completed_connection !== undefined &&+ status.completed_connection >= completionToken),);} catch (cause) {+ if (cause instanceof AnalysisError) return err(cause);return err(new AnalysisCapabilityUnavailableError("cutter",- "cutter_command_status",+ "cutter_command",cause instanceof Error ? cause.message : "Cutter status failed",- { cause },+ { cause, diagnostics: { auxiliary_operation: "status" } },),);}}- async #recoverCompletedCommands(+ async #readCommandStatus(descriptor: z.infer<typeof descriptorSchema>,signal?: AbortSignal,- ): Promise<void> {+ ): Promise<z.infer<typeof responseSchema>> {const raw = await this.#request(descriptor,serializeRequest(descriptor, {@@ -591,18 +573,30 @@ export class CutterBridgeClient {status.data.session_id !== descriptor.session_id)throw new AnalysisOutputError(- "cutter_command_status",+ "cutter_command","The bridge status response did not contain a valid session identity.",- { cause: status.success ? undefined : status.error },+ {+ cause: status.success ? undefined : status.error,+ diagnostics: { auxiliary_operation: "status" },+ },);- if (status.data.completed_connection === undefined)+ return status.data;+ }++ async #recoverCompletedCommands(+ descriptor: z.infer<typeof descriptorSchema>,+ signal?: AbortSignal,+ ): Promise<void> {+ const status = await this.#readCommandStatus(descriptor, signal);+ if (status.completed_connection === undefined)throw new AnalysisOutputError(- "cutter_command_status",+ "cutter_command","The bridge did not provide authenticated proof that earlier connections reached a terminal state.",+ { diagnostics: { auxiliary_operation: "status" } },);const pending =this.#pendingAcknowledgements.get(descriptor.session_id) ?? new Set();- for (const receipt of status.data.completed_commands ?? [])+ for (const receipt of status.completed_commands ?? [])pending.add(receipt.request_id);if (pending.size > 0)this.#pendingAcknowledgements.set(descriptor.session_id, pending);diff --git a/tests/boundary/cli/cutterStatusAttributionCli.test.ts b/tests/boundary/cli/cutterStatusAttributionCli.test.tsnew file mode 100644index 000000000..c88685864--- /dev/null+++ b/tests/boundary/cli/cutterStatusAttributionCli.test.ts@@ -0,0 +1,121 @@+import { expect } from "vitest";+import { chmod } from "node:fs/promises";+import { workspaceCliTest } from "../../support/cli/workspaceCliFixture.js";+import {+ authenticatedServer,+ writeDescriptor,+} from "../../fixtures/cutterBridgeProtocol.js";++const sessionId = "27d3e3f1-f1e5-49ae-91ec-95af1f343a5a";+workspaceCliTest.for([+ "missing-watermark",+ "invalid-identity",+ "valid",+] as const)(+ "retains caller operation and preflight proof through the CLI: %s",+ async (mode, { cli, workspace }) => {+ const directory = await workspace.mkdir("bridge");+ if (process.platform !== "win32") await chmod(directory, 0o700);+ const token = "synthetic-cutter-status-test-token";+ const calls: string[] = [];+ let phase = "discovery";+ const bridge = authenticatedServer(+ token,+ sessionId,+ (request, respond) => {+ calls.push(`${phase}:${String(request.kind)}`);+ if (request.kind === "ack") {+ respond({ ok: true, acknowledged: true });+ return;+ }+ if (request.kind === "status") {+ respond({+ ok: true,+ session_id:+ mode === "invalid-identity" && phase === "command"+ ? "00000000-0000-4000-8000-000000000001"+ : sessionId,+ current_file: null,+ document_generation: 0,+ cutter_version: "Cutter fixture",+ identity_status: "partial",+ completed_commands: [],+ ...(mode === "missing-watermark"+ ? {}+ : { completed_connection: "0000000000000000" }),+ });+ return;+ }+ expect(request.kind).toBe("command");+ expect(request.command).toBe("ij");+ respond({+ ok: true,+ session_id: sessionId,+ output: "fixture output",+ document_generation: 0,+ current_file: null,+ execution_state: "complete",+ output_truncated: false,+ });+ },+ true,+ );+ await new Promise<void>((resolve) =>+ bridge.listen(0, "127.0.0.1", resolve),+ );+ try {+ const address = bridge.address();+ if (address === null || typeof address === "string")+ throw new Error("Missing bridge address");+ await writeDescriptor(directory, sessionId, address.port, token);+ const environment = {+ ...workspace.environment,+ REA_CUTTER_BRIDGE_DIR: directory,+ REA_LOG_LEVEL: "silent",+ };+ const discovery = await cli.run({+ arguments: ["list-cutter-sessions", "--json"],+ environment,+ });+ expect(discovery.exitCode).toBe(0);+ expect(discovery.json).toMatchObject({+ discovery_status: "sessions_found",+ sessions: [{ session_id: sessionId }],+ });+ phase = "command";+ const result = await cli.run({+ arguments: ["cutter-command", sessionId, "0", "ij", "--json"],+ environment,+ });+ expect(result.stderr).toBe("");+ if (mode === "valid") {+ expect(result.exitCode).toBe(0);+ expect(result.json).toMatchObject({+ operation: "cutter_command",+ normalized_result: {+ output: "fixture output",+ execution_state: "complete",+ },+ });+ expect(calls).toContain("command:command");+ expect(calls).toContain("command:ack");+ } else {+ expect(result.exitCode).toBe(1);+ expect(result.json).toMatchObject({+ code: "unreadable_output",+ details: {+ operation: "cutter_command",+ reason:+ mode === "missing-watermark"+ ? "The bridge did not provide authenticated proof that earlier connections reached a terminal state."+ : "The bridge status response did not contain a valid session identity.",+ diagnostics: { auxiliary_operation: "status" },+ },+ });+ expect(calls).toEqual(["discovery:status", "command:status"]);+ }+ } finally {+ await new Promise<void>((resolve) => bridge.close(() => resolve()));+ }+ },+);diff --git a/tests/boundary/providers/CutterBridgeClient.test.ts b/tests/boundary/providers/CutterBridgeClient.test.tsindex a4e52087c..4a77cf6fc 100644--- a/tests/boundary/providers/CutterBridgeClient.test.ts+++ b/tests/boundary/providers/CutterBridgeClient.test.ts@@ -1,5 +1,8 @@+import {+ authenticatedServer,+ writeDescriptor,+} from "../../fixtures/cutterBridgeProtocol.js";import { createServer } from "node:net";-import { createHmac } from "node:crypto";import { readFileSync } from "node:fs";import {chmod,@@ -28,112 +31,6 @@ const listen = async (return address.port;};-const authenticatedServer = (- token: string,- sessionId: string,- onRequest: (- request: Record<string, unknown>,- respond: (- value: unknown,- options?: { raw?: boolean; fragment?: boolean; chunkBytes?: number },- ) => void,- connection: import("node:net").Socket,- ) => void,- handleStatusRequests = false,-): ReturnType<typeof createServer> => {- let nextConnectionOrdinal = 0;- return createServer((connection) => {- const connectionOrdinal = ++nextConnectionOrdinal;- connection.setEncoding("utf8");- let input = "";- let clientNonce = "";- let serverNonce = "";- connection.on("data", (chunk: string) => {- input += chunk;- for (;;) {- const end = input.indexOf("\n");- if (end < 0) return;- const frame = JSON.parse(input.slice(0, end)) as Record<- string,- unknown- >;- input = input.slice(end + 1);- if (frame.kind === "rea-auth-v2") {- clientNonce = String(frame.nonce);- serverNonce = `${connectionOrdinal.toString(16).padStart(16, "0")}${"e".repeat(48)}`;- const proof = createHmac("sha256", token)- .update(- `rea-cutter-server-v2:${sessionId}:${clientNonce}:${serverNonce}`,- )- .digest("hex");- connection.write(- `${JSON.stringify({ session_id: sessionId, nonce: serverNonce, proof })}\n`,- );- continue;- }- const requestBytes = String(frame.request);- const expected = createHmac("sha256", token)- .update(- `rea-cutter-client-v2:${sessionId}:${clientNonce}:${serverNonce}:${requestBytes}`,- )- .digest("hex");- if (frame.proof !== expected) {- connection.destroy();- return;- }- const respond = (- value: unknown,- options: {- raw?: boolean;- fragment?: boolean;- chunkBytes?: number;- } = {},- ): void => {- const response =- options.raw === true ? String(value) : JSON.stringify(value);- const responseProof = createHmac("sha256", token)- .update(- `rea-cutter-response-v2:${sessionId}:${clientNonce}:${serverNonce}:${response}`,- )- .digest("hex");- const frame = `${JSON.stringify({ response, proof: responseProof })}\n`;- const bytes = Buffer.from(frame);- if (options.chunkBytes !== undefined) {- const writeChunk = (offset: number): void => {- if (connection.destroyed) return;- const end = Math.min(offset + options.chunkBytes!, bytes.length);- if (offset === bytes.length) {- connection.end();- return;- }- connection.write(bytes.subarray(offset, end));- setImmediate(() => writeChunk(end));- };- setImmediate(() => writeChunk(0));- } else if (options.fragment === true) {- const midpoint = Math.floor(bytes.length / 2);- connection.write(bytes.subarray(0, midpoint));- setImmediate(() => connection.end(bytes.subarray(midpoint)));- } else connection.end(frame);- };- const request = JSON.parse(requestBytes) as Record<string, unknown>;- if (request.kind === "status" && !handleStatusRequests) {- respond({- ok: true,- session_id: sessionId,- completed_commands: [],- completed_connection: (connectionOrdinal - 1)- .toString(16)- .padStart(16, "0"),- });- continue;- }- onRequest(request, respond, connection);- }- });- });-};-const statusServer = (token: string,currentFile: string | null,@@ -170,32 +67,6 @@ const createStatusHarness = (return { server, requestText: () => requestText };};-const writeDescriptor = async (- directory: string,- sessionId: string,- port: number,- token: string,- options: {- readonly currentFile?: string | null;- readonly documentGeneration?: number;- } = {},-): Promise<void> =>- writeFile(- join(directory, `cutter-${process.pid}-${sessionId}.json`),- JSON.stringify({- session_id: sessionId,- pid: process.pid,- host: "127.0.0.1",- port,- token,- document_generation: options.documentGeneration ?? 0,- current_file: options.currentFile ?? null,- cutter_version: "Cutter fixture version",- identity_status: "partial",- }),- { mode: 0o600 },- );-const expectDiscoveredSession = (result: unknown,sessionId: string,diff --git a/tests/boundary/providers/CutterStatusProof.test.ts b/tests/boundary/providers/CutterStatusProof.test.tsnew file mode 100644index 000000000..2b4fa97b1--- /dev/null+++ b/tests/boundary/providers/CutterStatusProof.test.ts@@ -0,0 +1,71 @@+import { it, expect, onTestFinished } from "vitest";+import {+ authenticatedServer,+ writeDescriptor,+} from "../../fixtures/cutterBridgeProtocol.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";+import { CutterBridgeClient } from "../../../src/cutter/CutterBridgeClient.js";+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";++it.each(["invalid-identity", "exact-receipt", "unrelated-receipt"] as const)(+ "checks command completion independently of preflight watermark admission: %s",+ async (mode) => {+ const directory = await createTestTempDirectory("rea-cutter-status-proof-");+ const sessionId = "27d3e3f1-f1e5-49ae-91ec-95af1f343a5a";+ const requestId = "4b18ce4d-bf31-456e-ae31-e8c547b2f9db";+ const otherId = "ede4bbfd-6348-46aa-963b-0de0e78ccbdc";+ const token = "synthetic-cutter-status-proof-token";+ const calls: string[] = [];+ const server = authenticatedServer(+ token,+ sessionId,+ (request, respond) => {+ calls.push(String(request.kind));+ if (request.kind === "ack") {+ expect(request.request_id).toBe(requestId);+ respond({ ok: true, acknowledged: true });+ return;+ }+ respond({+ ok: true,+ session_id: mode === "invalid-identity" ? otherId : sessionId,+ completed_commands: [+ {+ request_id: mode === "exact-receipt" ? requestId : otherId,+ execution_state: "complete",+ },+ ],+ });+ },+ true,+ );+ onTestFinished(+ async () => new Promise<void>((resolve) => server.close(() => resolve())),+ );+ await new Promise<void>((resolve) =>+ server.listen(0, "127.0.0.1", resolve),+ );+ const address = server.address();+ if (address === null || typeof address === "string")+ throw new Error("Missing listener");+ const port = address.port;+ await writeDescriptor(directory, sessionId, port, token);+ const client = new CutterBridgeClient({ REA_CUTTER_BRIDGE_DIR: directory });+ const result = await client.confirmCommandCompletion(sessionId, requestId);+ if (mode === "invalid-identity") {+ if (result.ok) throw new Error("Expected invalid status identity");+ expect(projectAnalysisError(result.error)).toMatchObject({+ code: "unreadable_output",+ details: {+ operation: "cutter_command",+ diagnostics: { auxiliary_operation: "status" },+ },+ });+ } else+ expect(result).toEqual({ ok: true, value: mode === "exact-receipt" });+ expect(calls).toEqual(+ mode === "exact-receipt" ? ["status", "ack"] : ["status"],+ );+ await client.close();+ },+);diff --git a/tests/fixtures/cutterBridgeProtocol.ts b/tests/fixtures/cutterBridgeProtocol.tsnew file mode 100644index 000000000..2103a8753--- /dev/null+++ b/tests/fixtures/cutterBridgeProtocol.ts@@ -0,0 +1,137 @@+import { writeFile } from "node:fs/promises";+import { join } from "node:path";+import { createServer } from "node:net";+import { createHmac } from "node:crypto";++/** Authenticate real v2 frames before dispatching controlled bridge replies. */+export const authenticatedServer = (+ token: string,+ sessionId: string,+ onRequest: (+ request: Record<string, unknown>,+ respond: (+ value: unknown,+ options?: { raw?: boolean; fragment?: boolean; chunkBytes?: number },+ ) => void,+ connection: import("node:net").Socket,+ ) => void,+ handleStatusRequests = false,+): ReturnType<typeof createServer> => {+ let nextConnectionOrdinal = 0;+ return createServer((connection) => {+ const connectionOrdinal = ++nextConnectionOrdinal;+ connection.setEncoding("utf8");+ let input = "";+ let clientNonce = "";+ let serverNonce = "";+ connection.on("data", (chunk: string) => {+ input += chunk;+ for (;;) {+ const end = input.indexOf("\n");+ if (end < 0) return;+ const frame = JSON.parse(input.slice(0, end)) as Record<+ string,+ unknown+ >;+ input = input.slice(end + 1);+ if (frame.kind === "rea-auth-v2") {+ clientNonce = String(frame.nonce);+ serverNonce = `${connectionOrdinal.toString(16).padStart(16, "0")}${"e".repeat(48)}`;+ const proof = createHmac("sha256", token)+ .update(+ `rea-cutter-server-v2:${sessionId}:${clientNonce}:${serverNonce}`,+ )+ .digest("hex");+ connection.write(+ `${JSON.stringify({ session_id: sessionId, nonce: serverNonce, proof })}\n`,+ );+ continue;+ }+ const requestBytes = String(frame.request);+ const expected = createHmac("sha256", token)+ .update(+ `rea-cutter-client-v2:${sessionId}:${clientNonce}:${serverNonce}:${requestBytes}`,+ )+ .digest("hex");+ if (frame.proof !== expected) {+ connection.destroy();+ return;+ }+ const respond = (+ value: unknown,+ options: {+ raw?: boolean;+ fragment?: boolean;+ chunkBytes?: number;+ } = {},+ ): void => {+ const response =+ options.raw === true ? String(value) : JSON.stringify(value);+ const responseProof = createHmac("sha256", token)+ .update(+ `rea-cutter-response-v2:${sessionId}:${clientNonce}:${serverNonce}:${response}`,+ )+ .digest("hex");+ const frame = `${JSON.stringify({ response, proof: responseProof })}\n`;+ const bytes = Buffer.from(frame);+ if (options.chunkBytes !== undefined) {+ const writeChunk = (offset: number): void => {+ if (connection.destroyed) return;+ const end = Math.min(offset + options.chunkBytes!, bytes.length);+ if (offset === bytes.length) {+ connection.end();+ return;+ }+ connection.write(bytes.subarray(offset, end));+ setImmediate(() => writeChunk(end));+ };+ setImmediate(() => writeChunk(0));+ } else if (options.fragment === true) {+ const midpoint = Math.floor(bytes.length / 2);+ connection.write(bytes.subarray(0, midpoint));+ setImmediate(() => connection.end(bytes.subarray(midpoint)));+ } else connection.end(frame);+ };+ const request = JSON.parse(requestBytes) as Record<string, unknown>;+ if (request.kind === "status" && !handleStatusRequests) {+ respond({+ ok: true,+ session_id: sessionId,+ completed_commands: [],+ completed_connection: (connectionOrdinal - 1)+ .toString(16)+ .padStart(16, "0"),+ });+ continue;+ }+ onRequest(request, respond, connection);+ }+ });+ });+};++export const writeDescriptor = async (+ directory: string,+ sessionId: string,+ port: number,+ token: string,+ options: {+ readonly currentFile?: string | null;+ readonly documentGeneration?: number;+ } = {},+): Promise<void> =>+ writeFile(+ join(directory, `cutter-${process.pid}-${sessionId}.json`),+ JSON.stringify({+ session_id: sessionId,+ pid: process.pid,+ host: "127.0.0.1",+ port,+ token,+ document_generation: options.documentGeneration ?? 0,+ current_file: options.currentFile ?? null,+ cutter_version: "Cutter fixture version",+ identity_status: "partial",+ }),+ { mode: 0o600 },+ );