Files
reverse-engineering-anything/src/cutter/CutterBridgeService.ts
T

278 lines
10 KiB
TypeScript

import { unknownTarget } from "../domain/targetIdentity.js";
import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCleanup.js";
import { AnalysisCleanupRelease } from "../domain/analysisCleanupRelease.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import {
AnalysisCapabilityUnavailableError,
AnalysisInputError,
AnalysisOutputError,
cancelledBy,
} from "../domain/analysisErrorCore.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { createEvidence, type Evidence } from "../domain/evidence.js";
import { err, ok, type Result } from "../domain/result.js";
import { cutterCommandInputSchema } from "../contracts/cutterToolContracts.js";
import type { CutterBridgeDiscovery } from "../domain/cutterDiscovery.js";
import {
CutterBridgeClient,
type CutterBridgeExecution,
type CutterDiscoveryOptions,
} from "./CutterBridgeClient.js";
import { CUTTER_PROVIDER_IDENTITY } from "./CutterProviderIdentity.js";
import { errorMessage } from "../kernel/errorMessage.js";
interface CutterBridgePort {
listSessions(
options?: CutterDiscoveryOptions,
): Promise<CutterBridgeDiscovery>;
close?(): Promise<void>;
retryDescriptorCleanup?(): Promise<void>;
confirmCommandCompletion?(
sessionId: string,
requestId: string,
completionToken?: string,
): Promise<Result<boolean, AnalysisError>>;
execute(input: {
readonly sessionId: string;
readonly expectedGeneration: number;
readonly command: string;
readonly json: boolean;
readonly signal?: AbortSignal;
}): Promise<CutterBridgeExecution>;
}
/** Shared Cutter bridge workflows used by the MCP adapter and CLI. */
export class CutterBridgeService {
#cleanupAttempt: Promise<Result<null, AnalysisError>> | undefined;
readonly #pendingCleanup = new Map<
string,
{
readonly sessionId: string;
readonly completionToken?: string;
readonly failure: AnalysisOutputError;
/** Confirmed by the producer's terminal receipt; the failure reads it. */
readonly release: AnalysisCleanupRelease;
}
>();
constructor(readonly client: CutterBridgePort = new CutterBridgeClient()) {}
/** Release timed-out work only after producer-owned terminal proof. */
retryCleanup(): Promise<Result<null, AnalysisError>> {
if (this.#cleanupAttempt !== undefined) return this.#cleanupAttempt;
const attempt = this.#retryPendingCleanup().finally(() => {
if (this.#cleanupAttempt === attempt) this.#cleanupAttempt = undefined;
});
this.#cleanupAttempt = attempt;
return attempt;
}
async #retryPendingCleanup(): Promise<Result<null, AnalysisError>> {
for (const [requestId, pending] of this.#pendingCleanup) {
const confirmCommandCompletion = this.client.confirmCommandCompletion;
if (confirmCommandCompletion === undefined) return err(pending.failure);
const receipt = await confirmCommandCompletion.call(
this.client,
pending.sessionId,
requestId,
pending.completionToken,
);
if (!receipt.ok)
return err(
analysisErrorWithCleanupDependencies(
pending.failure,
receipt.error,
"cutter_command",
),
);
if (!receipt.value) return err(pending.failure);
pending.release.confirm();
this.#pendingCleanup.delete(requestId);
}
return ok(null);
}
async listSessions(
options: CutterDiscoveryOptions = {},
): Promise<Result<CutterBridgeDiscovery, AnalysisError>> {
const { signal } = options;
if (signal?.aborted)
return err(cancelledBy("list_cutter_sessions", signal));
try {
const discovery = await this.client.listSessions(options);
if (signal?.aborted)
return err(cancelledBy("list_cutter_sessions", signal));
return ok(discovery);
} catch (cause) {
if (cause instanceof AnalysisError) return err(cause);
return err(
new AnalysisCapabilityUnavailableError(
"cutter",
"list_cutter_sessions",
cause instanceof Error ? cause.message : "Cutter discovery failed",
{ cause },
),
);
}
}
async close(): Promise<void> {
const pending = await this.retryCleanup();
try {
if (pending.ok) await this.client.close?.();
else await this.client.retryDescriptorCleanup?.();
} catch (cause: unknown) {
const failure =
cause instanceof AnalysisError
? cause
: new ProviderCleanupError(
"cutter",
[],
{
reason: errorMessage(cause),
},
{ cause },
);
throw pending.ok
? failure
: analysisErrorWithCleanupDependencies(
pending.error,
failure,
"close_cutter",
);
}
if (!pending.ok) throw pending.error;
}
async execute(
rawInput: unknown,
options: { readonly signal?: AbortSignal } = {},
): Promise<Result<Evidence, AnalysisError>> {
const parsed = cutterCommandInputSchema.safeParse(rawInput);
if (!parsed.success) return err(new AnalysisInputError("cutter_command"));
if (options.signal?.aborted)
return err(cancelledBy("cutter_command", options.signal));
const input = parsed.data;
const cleanup = await this.retryCleanup();
if (!cleanup.ok) return cleanup;
try {
const output = await this.client.execute({
sessionId: input.session_id,
expectedGeneration: input.expected_generation,
command: input.command,
json: input.json,
...(options.signal === undefined ? {} : { signal: options.signal }),
});
const normalizedOutput = jsonValueSchema.parse(output.output);
const evidence = createEvidence(
unknownTarget("not-observed"),
{
...CUTTER_PROVIDER_IDENTITY,
version: output.cutterVersion,
},
{
predicateType: "rea.cutter.command-observation",
operation: "cutter_command",
parameters: {
session_id: input.session_id,
expected_generation: input.expected_generation,
command: input.command,
json: input.json,
},
result: {
command: input.command,
output: normalizedOutput,
execution_state: output.executionState,
error: output.error,
message: output.message,
output_truncated: output.outputTruncated,
cutter_version: output.cutterVersion,
current_file: output.currentFile,
document_generation: output.documentGeneration,
identity_status: output.identityStatus,
},
rawResult: normalizedOutput,
authority: "external-service",
limitations: [
"Cutter exposes no verified stable identity for the active unsaved document or tab.",
"Document identity is partial: the bridge uses a plugin instance UUID and observed generation; a same-path tab switch or reload may not be distinguishable.",
"Cutter command effects depend on the Rizin command and active plugins.",
"The local IPC protocol is implemented by REA and is not an upstream Cutter API.",
...(input.json
? [
"JSON integer literals outside JavaScript's safe integer range are retained as decimal strings.",
]
: []),
...(output.executionState === "unknown"
? [
"Command completion or its output could not be confirmed; do not retry automatically because the command may have produced partial or persistent effects.",
]
: []),
...(output.outputTruncated === true
? [
"The command completed or may have completed, but output exceeded the bridge transport limit and was omitted.",
]
: output.outputTruncated === null
? [
"The bridge did not declare whether output was omitted, so the output may be incomplete.",
]
: []),
...(output.documentGeneration === null
? [
"The bridge did not report the document generation after this command; list Cutter sessions again before selecting an expected_generation.",
]
: []),
],
},
);
if (output.executionState === "unknown") {
const failure = new AnalysisOutputError(
"cutter_command",
"Cutter command completion is unknown; the bound binary remains unavailable until the UI dispatcher confirms this request reached a terminal state.",
{
cleanup: {
reason:
"The exact UI dispatcher completion receipt has not arrived; the dispatched command may still be running.",
resources: [`cutter-session:${input.session_id}`],
},
partialObservation: evidence,
...(output.outputLimit === undefined
? {}
: { limit: output.outputLimit }),
},
);
const release = new AnalysisCleanupRelease();
this.#pendingCleanup.set(output.requestId, {
sessionId: input.session_id,
...(output.completionToken === undefined
? {}
: { completionToken: output.completionToken }),
failure: release.bind(failure),
release,
});
return err(failure);
}
if (options.signal?.aborted)
return err(
cancelledBy("cutter_command", options.signal, {
partialObservation: evidence,
}),
);
return ok(evidence);
} catch (cause) {
if (cause instanceof AnalysisError) return err(cause);
return err(
new AnalysisCapabilityUnavailableError(
"cutter",
"cutter_command",
cause instanceof Error
? cause.message
: "Unknown Cutter bridge failure",
{ cause },
),
);
}
}
}