Files
reverse-engineering-anything/src/ghidra/GhidraSessionError.ts
T
gensokyo-dev c07ab4b994 feat(ghidra): checkpoint owned Programs across sessions
Add opt-in REA_GHIDRA_CHECKPOINT_DIR for owned Ghidra Program persistence through the shared CLI/MCP provider. Save completed initial analysis and metadata changes on normal close; verify and restore the last successful packed Program without auto-analysis.

Preserve generation identity, exclusive ownership, typed cancellation and cleanup retry. Refresh checkpoint-dependent profiles after retirement, including failed-switch restoration, while retaining caller selection provenance. Keep source executables and caller projects unchanged.

Validated with 720 focused tests (3 platform skips), 13 real Ghidra CLI/MCP scenarios, static/docs checks and CI. Review findings addressed. No version bump or release publication.

Refs #8165.
2026-11-07 14:52:39 +08:00

572 lines
19 KiB
TypeScript

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 type { GhidraDiagnosticsScope } from "./GhidraDiagnostics.js";
import { ghidraFileOffsetOutcome } from "./GhidraFileOffsetFailure.js";
import { GhidraAdmissionError } from "./GhidraAdmissionError.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 =
| "admission"
| "cancelled"
| "timeout"
| "start"
| "process"
| "protocol"
| "checkpoint"
| "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;
/** Caller cancellation that closed the session while this failure settled. */
readonly concurrentCancellation?: { readonly reason: unknown };
}
/** 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;
readonly concurrentCancellation: { readonly reason: unknown } | 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;
this.concurrentCancellation = options.concurrentCancellation;
}
/** 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,
);
}
/**
* Keep this failure primary while recording that caller cancellation closed
* the session before it settled, so projections do not promise reuse.
*/
withConcurrentCancellation(cancellation: {
readonly reason: unknown;
}): GhidraSessionError {
return this.#copy(
{ ...this.diagnostics, session_closed_by_cancellation: true },
this.cleanupFailure,
this.message,
this.partialObservation,
cancellation,
);
}
#copy(
diagnostics: Readonly<Record<string, JsonValue>>,
cleanupFailure: AnalysisError | undefined,
message = this.message,
partialObservation = this.partialObservation,
concurrentCancellation = this.concurrentCancellation,
): 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 }),
...(concurrentCancellation === undefined
? {}
: { concurrentCancellation }),
});
}
}
/** 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 }),
},
);
/** Bridge input failures share classification with their domain error projection. */
export const isGhidraInputFailureCode = (code: string | undefined): boolean =>
code === "invalid_request" ||
code === "invalid_regex_pattern" ||
code === "not_found" ||
code === "procedure_not_found" ||
code === "file_offset_unmapped" ||
code === "procedure_ambiguous" ||
code === "file_offset_ambiguous" ||
code === "ambiguous";
/** Bind session-failure construction to its causal diagnostic scope. */
export const bindGhidraSessionFailure =
(
diagnostics: (
scope: GhidraDiagnosticsScope,
) => 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(
kind === "remote" &&
(isGhidraInputFailureCode(options.remoteCode) ||
options.remoteCode === "invalid_function_name" ||
ghidraFileOffsetOutcome(options.remoteCode) !== undefined)
? "request"
: "session",
),
...(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),
...causeAdmissionDetail(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 causeAdmissionDetail = (
cause: Error,
redact: (value: string, incomplete?: boolean) => string,
): Record<string, JsonValue> => {
if (!(cause instanceof GhidraAdmissionError) || cause.detail === undefined)
return {};
const detail: Record<string, JsonValue> = {};
for (const [key, value] of Object.entries(cause.detail)) {
if (typeof value === "number") {
detail[key] = value;
continue;
}
const bounded = boundedUtf8Text(redact(value), MAX_CAUSE_FIELD_BYTES);
detail[key] = bounded.text;
}
return { detail };
};
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) };
};