Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import {
AnalysisError,
type AnalysisPartialObservation,
} from "../domain/analysisErrorBase.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";
import { boundedUtf8Text } from "../process/boundedUtf8Text.js";
import { GhidraLaunchSupportError } from "./GhidraJavaLaunch.js";
import {
GhidraLaunchError,
GHIDRA_LAUNCH_COMMAND_OUTPUT_BYTES,
} from "./GhidraLauncher.js";
const MAX_CAUSE_DEPTH = 3;
const MAX_CAUSE_MESSAGE_BYTES = 2 * 1024;
const MAX_CAUSE_FIELD_BYTES = 1024;
const MAX_COMPILER_STDERR_BYTES = 8 * 1024;
const MAX_COMMAND_OUTPUT_BYTES = 8 * 1024;
/** Stable failure phase for one private Ghidra headless session. */
export type GhidraSessionFailureKind =
| "cancelled"
| "timeout"
| "start"
| "process"
| "protocol"
| "remote"
| "analysis_timeout";
/** Message of the failure raised when the provider startup deadline elapses. */
export const GHIDRA_STARTUP_DEADLINE_ELAPSED =
"Ghidra startup deadline elapsed";
/** Additional structured context for a Ghidra session failure. */
export interface GhidraSessionErrorOptions extends ErrorOptions {
readonly cancellation?: { readonly reason: unknown };
readonly partialObservation?: AnalysisPartialObservation;
readonly timeoutMs?: number;
readonly remoteCode?: string;
readonly cleanupFailure?: AnalysisError;
}
/** Provider-owned failure with bounded, token-redacted local diagnostics. */
export class GhidraSessionError extends Error {
readonly diagnostics: Readonly<Record<string, JsonValue>>;
readonly timeoutMs: number | undefined;
readonly remoteCode: string | undefined;
readonly cleanupFailure: AnalysisError | undefined;
readonly cancellation: { readonly reason: unknown } | undefined;
readonly partialObservation: AnalysisPartialObservation | undefined;
constructor(
readonly kind: GhidraSessionFailureKind,
message: string,
diagnostics: Readonly<Record<string, JsonValue>> = {},
options: GhidraSessionErrorOptions = {},
) {
super(message, options);
this.name = "GhidraSessionError";
this.diagnostics = structuredClone(diagnostics);
this.timeoutMs = options.timeoutMs;
this.remoteCode = options.remoteCode;
this.cleanupFailure = options.cleanupFailure;
this.cancellation = options.cancellation;
this.partialObservation = options.partialObservation;
}
/** Refresh diagnostics without discarding owned failure or cleanup facts. */
withDiagnostics(
diagnostics: Readonly<Record<string, JsonValue>>,
message = this.message,
): GhidraSessionError {
return this.#copy(diagnostics, this.cleanupFailure, message);
}
/** Join cleanup uncertainty, following both exact owners through later retry. */
withCleanupFailure(
cleanup: AnalysisError,
diagnostics = this.diagnostics,
): GhidraSessionError {
const combined =
this.cleanupFailure === undefined || this.cleanupFailure === cleanup
? cleanup
: analysisErrorWithCleanupFailure(
this.cleanupFailure,
cleanup,
).bindCleanupDependencies([this.cleanupFailure, cleanup]);
return this.#copy(diagnostics, combined);
}
/** Retain caller-safe completed facts without serializing snapshot byte buffers. */
withPartialObservation(
observation: AnalysisPartialObservation,
): GhidraSessionError {
return this.#copy(
this.diagnostics,
this.cleanupFailure,
this.message,
observation,
);
}
#copy(
diagnostics: Readonly<Record<string, JsonValue>>,
cleanupFailure: AnalysisError | undefined,
message = this.message,
partialObservation = this.partialObservation,
): GhidraSessionError {
return new GhidraSessionError(this.kind, message, diagnostics, {
...(Object.hasOwn(this, "cause") ? { cause: this.cause } : {}),
...(this.cancellation === undefined
? {}
: { cancellation: this.cancellation }),
...(this.timeoutMs === undefined ? {} : { timeoutMs: this.timeoutMs }),
...(this.remoteCode === undefined ? {} : { remoteCode: this.remoteCode }),
...(cleanupFailure === undefined ? {} : { cleanupFailure }),
...(partialObservation === undefined ? {} : { partialObservation }),
});
}
}
/** Build a session failure while preserving bounded remote failure metadata. */
const createGhidraSessionError = (failure: {
readonly kind: GhidraSessionFailureKind;
readonly message: string;
readonly diagnostics: Readonly<Record<string, JsonValue>>;
readonly cause?: unknown;
readonly timeoutMs?: number;
readonly remoteCode?: string;
readonly cancellation?: { readonly reason: unknown };
readonly redact: (value: string, incomplete?: boolean) => string;
}): GhidraSessionError =>
new GhidraSessionError(
failure.kind,
failure.message,
{
...failure.diagnostics,
failure_kind: failure.kind,
failure_message: failure.message,
...(failure.remoteCode === undefined
? {}
: {
remote_code: failure.redact(failure.remoteCode),
remote_message: failure.message,
}),
},
{
...(failure.cancellation === undefined
? {}
: { cancellation: failure.cancellation }),
...(failure.cause === undefined ? {} : { cause: failure.cause }),
...(failure.timeoutMs === undefined
? {}
: { timeoutMs: failure.timeoutMs }),
...(failure.remoteCode === undefined
? {}
: { remoteCode: failure.remoteCode }),
},
);
/** Bind session-failure construction to a live, token-redacted diagnostic view. */
export const bindGhidraSessionFailure =
(
diagnostics: () => Readonly<Record<string, JsonValue>>,
redact: (value: string, incomplete?: boolean) => string = (value) => value,
) =>
(
kind: GhidraSessionFailureKind,
message: string,
cause?: unknown,
options: Pick<
GhidraSessionErrorOptions,
"timeoutMs" | "remoteCode" | "cancellation"
> = {},
): GhidraSessionError => {
const failure = createGhidraSessionError({
kind,
message: redact(message),
diagnostics: {
...diagnostics(),
...(cause === undefined
? {}
: { failure_cause: describeCause(cause, redact) }),
},
redact,
...(cause === undefined ? {} : { cause }),
...options,
});
const cleanup =
cause instanceof DarwinProcessOwnershipInspectionError ||
cause instanceof GhidraLaunchError
? cause.cleanupFailure
: cause instanceof AnalysisError && cause.cleanupIncomplete
? cause
: undefined;
return cleanup === undefined
? failure
: failure.withCleanupFailure(cleanup);
};
/** Canonical factory contract shared by session lifecycle owners. */
export type GhidraSessionFailureFactory = ReturnType<
typeof bindGhidraSessionFailure
>;
const describeCause = (
cause: unknown,
redact: (value: string, incomplete?: boolean) => string,
depth = 0,
): JsonValue => {
if (cause instanceof Error) {
return describeErrorCause(cause, redact, depth);
}
if (typeof cause === "string") {
const message = boundedUtf8Text(redact(cause), MAX_CAUSE_MESSAGE_BYTES);
return {
type: "string",
message: message.text,
...(message.truncated ? { message_truncated: true } : {}),
};
}
if (cause === null || typeof cause === "boolean")
return { type: cause === null ? "null" : "boolean", value: cause };
if (typeof cause === "number" && Number.isFinite(cause))
return { type: "number", value: cause };
return { type: typeof cause };
};
const describeErrorCause = (
cause: Error,
redact: (value: string, incomplete?: boolean) => string,
depth: number,
): JsonValue => {
const message = boundedUtf8Text(
redact(cause.message),
MAX_CAUSE_MESSAGE_BYTES,
);
const name = boundedUtf8Text(redact(cause.name), MAX_CAUSE_FIELD_BYTES);
return {
name: name.text,
...(name.truncated ? { name_truncated: true } : {}),
message: message.text,
...(message.truncated ? { message_truncated: true } : {}),
...causeCode(cause, redact),
...causeSignal(cause, redact),
...causeCommandOutcome(cause, redact),
...causeCompilerOutcome(cause, redact),
...causeLaunchOutcome(cause, redact),
...causeLaunchRollback(cause, redact, depth),
...nestedErrorCause(cause, redact, depth),
};
};
const causeCommandOutcome = (
cause: Error,
redact: (value: string, incomplete?: boolean) => string,
): Record<string, JsonValue> => {
if (!(cause instanceof GhidraLaunchSupportError)) return {};
const outcome = cause.outcome;
if (outcome === undefined) return {};
const stdout = boundedUtf8Text(
redact(outcome.stdout, outcome.outputTruncated !== false),
MAX_COMMAND_OUTPUT_BYTES,
);
const stderr = boundedUtf8Text(
redact(outcome.stderr, outcome.outputTruncated !== false),
MAX_COMMAND_OUTPUT_BYTES,
);
return {
command_outcome: {
stdout: stdout.text,
stderr: stderr.text,
stdoutBytes: outcome.stdoutBytes ?? Buffer.byteLength(outcome.stdout),
stderrBytes: outcome.stderrBytes ?? Buffer.byteLength(outcome.stderr),
stdoutTruncated: stdout.truncated,
stderrTruncated: stderr.truncated,
outputTruncated: outcome.outputTruncated,
killed: outcome.killed,
},
};
};
const causeCode = (
cause: Error,
redact: (value: string, incomplete?: boolean) => string,
): Record<string, JsonValue> => {
const code = "code" in cause ? cause.code : undefined;
if (typeof code === "string") {
const bounded = boundedUtf8Text(redact(code), MAX_CAUSE_FIELD_BYTES);
return {
code: bounded.text,
...(bounded.truncated ? { code_truncated: true } : {}),
};
}
if (typeof code === "number" && Number.isFinite(code)) return { code };
return {};
};
const causeSignal = (
cause: Error,
redact: (value: string, incomplete?: boolean) => string,
): Record<string, JsonValue> => {
const signal = "signal" in cause ? cause.signal : undefined;
if (typeof signal === "string") {
const bounded = boundedUtf8Text(redact(signal), MAX_CAUSE_FIELD_BYTES);
return {
signal: bounded.text,
...(bounded.truncated ? { signal_truncated: true } : {}),
};
}
if (signal === null) return { signal: null };
return {};
};
const causeCompilerOutcome = (
cause: Error,
redact: (value: string, incomplete?: boolean) => string,
): Record<string, JsonValue> => {
if (!(cause instanceof DarwinProcessOwnershipInspectionError)) return {};
const outcome = cause.compilerOutcome;
if (outcome === undefined) return {};
const stderr = boundedUtf8Text(
redact(outcome.stderr),
MAX_COMPILER_STDERR_BYTES,
);
const code = boundedCompilerField(outcome.code, redact);
const signal = boundedCompilerField(outcome.signal, redact);
return {
compiler_outcome: {
...outcome,
code: code.value,
signal: signal.value,
stderr: stderr.text,
stderrTruncated: outcome.stderrTruncated || stderr.truncated,
...(code.truncated ? { codeTruncated: true } : {}),
...(signal.truncated ? { signalTruncated: true } : {}),
},
};
};
const boundedCompilerField = (
value: string | number | null,
redact: (value: string, incomplete?: boolean) => string,
): { readonly value: string | number | null; readonly truncated: boolean } => {
if (typeof value !== "string") return { value, truncated: false };
const bounded = boundedUtf8Text(redact(value), MAX_CAUSE_FIELD_BYTES);
return { value: bounded.text, truncated: bounded.truncated };
};
/** Project the producer's tagged rollback facts independently of the primary cause. */
const causeLaunchRollback = (
cause: Error,
redact: (value: string, incomplete?: boolean) => string,
depth: number,
): Record<string, JsonValue> => {
if (
!(cause instanceof GhidraLaunchError) ||
cause.rollbackFailure === undefined
)
return {};
const rollback = cause.rollbackFailure;
if (rollback.kind === "rejected")
return {
rollback_failure: {
kind: rollback.kind,
...(depth >= MAX_CAUSE_DEPTH
? { cause_truncated: true }
: { cause: describeCause(rollback.cause, redact, depth + 1) }),
},
};
const result = rollback.result;
const reason = boundedUtf8Text(
redact(result.reason),
MAX_CAUSE_MESSAGE_BYTES,
);
const diagnostic = (value: string | undefined): Record<string, JsonValue> => {
if (value === undefined) return {};
const bounded = boundedUtf8Text(redact(value), MAX_CAUSE_MESSAGE_BYTES);
return {
diagnostic: bounded.text,
...(bounded.truncated ? { diagnostic_truncated: true } : {}),
};
};
// Share one member-evidence budget, matching a retained launcher-command stream.
// Keep the complete typed result on GhidraLaunchError for the process owner.
let remainingBytes = GHIDRA_LAUNCH_COMMAND_OUTPUT_BYTES;
const members = <Member>(
values: readonly Member[],
project: (value: Member) => JsonValue,
): { readonly rows: JsonValue[]; readonly omitted: number } => {
const rows: JsonValue[] = [];
for (const value of values) {
const row = project(value);
const bytes =
Buffer.byteLength(JSON.stringify(row)) + (rows.length === 0 ? 0 : 1);
if (bytes > remainingBytes) break;
remainingBytes -= bytes;
rows.push(row);
}
return { rows, omitted: values.length - rows.length };
};
const failures =
result.failures === undefined
? undefined
: members(result.failures, (failure) => ({
pid: failure.pid,
reason: failure.reason,
...diagnostic(failure.diagnostic),
}));
const unverified =
result.unverified === undefined
? undefined
: members(result.unverified, (member) => ({
pid: member.pid,
...diagnostic(member.diagnostic),
}));
return {
rollback_failure: {
kind: rollback.kind,
result: {
cleaned: false,
reason: reason.text,
...(reason.truncated ? { reason_truncated: true } : {}),
...(failures === undefined
? {}
: {
failures: failures.rows,
...(failures.omitted === 0
? {}
: { failures_omitted: failures.omitted }),
}),
...(unverified === undefined
? {}
: {
unverified: unverified.rows,
...(unverified.omitted === 0
? {}
: { unverified_omitted: unverified.omitted }),
}),
},
},
};
};
/** Retain a launch failure's launcher command outcome in its cause envelope. */
const causeLaunchOutcome = (
cause: Error,
redact: (value: string, incomplete?: boolean) => string,
): Record<string, JsonValue> => {
if (!(cause instanceof GhidraLaunchError)) return {};
const launchSupport =
cause.launchSupport.length === 0
? {}
: {
launch_support: cause.launchSupport.map((output) => ({
...output,
stderr: redact(output.stderr),
})),
};
// A failed LaunchSupport helper reports its own command outcome in the
// nested cause; earlier helper warnings still belong to this launch.
if (cause.cause instanceof GhidraLaunchSupportError) return launchSupport;
const output = cause.capturedOutput;
if (output === undefined) return launchSupport;
const stdout = boundedUtf8Text(
redact(output.stdout),
GHIDRA_LAUNCH_COMMAND_OUTPUT_BYTES,
);
const stderr = boundedUtf8Text(
redact(output.stderr),
GHIDRA_LAUNCH_COMMAND_OUTPUT_BYTES,
);
const truncated = output.truncated || stdout.truncated || stderr.truncated;
return {
...launchSupport,
launch_outcome: {
stdout: stdout.text,
stderr: stderr.text,
truncated,
...(output.stdout_bytes === undefined
? {}
: { stdout_bytes: output.stdout_bytes }),
...(output.stderr_bytes === undefined
? {}
: { stderr_bytes: output.stderr_bytes }),
...(output.exit_code === undefined
? {}
: { exit_code: output.exit_code }),
...(output.signal === undefined ? {} : { signal: output.signal }),
},
};
};
const nestedErrorCause = (
cause: Error,
redact: (value: string, incomplete?: boolean) => string,
depth: number,
): Record<string, JsonValue> => {
if (!("cause" in cause)) return {};
if (depth >= MAX_CAUSE_DEPTH) return { cause_truncated: true };
return { cause: describeCause(cause.cause, redact, depth + 1) };
};