Files
rea/src/domain/hopperErrors.ts
T
morlutoandGitHub 601814ed0e fix(hopper): preserve observed process failures across requests (#1927)
* fix(hopper): preserve observed process failures across requests

* test(hopper): consolidate retained cleanup and recover failed helper fixtures

* docs(hopper): clarify first-use demo prompt and startup recovery
2026-10-12 02:13:53 +08:00

171 lines
5.5 KiB
TypeScript

import {
AnalysisError,
type AnalysisErrorOptions,
} from "./analysisErrorBase.js";
import type {
HopperProcessProviderState,
ProviderFailureStage,
} from "./providerOperationHealth.js";
import {
hopperStartupFailure,
type HopperStartupFailureCode,
type HopperStartupFailureDiagnostic,
} from "./hopperStartupFailure.js";
/** Base class for failures produced specifically by the Hopper provider. */
export abstract class HopperError extends AnalysisError {}
/** Observed launcher outcome; a helper exit does not establish GUI lifetime. */
export type HopperLauncherOutcome = {
readonly exit_code: number | null;
readonly signal: string | null;
/** Total bytes drained from the stream; retained_bytes reports captured bytes. */
readonly stdout: {
readonly text: string;
readonly bytes: number;
readonly retained_bytes: number;
};
readonly stderr: {
readonly text: string;
readonly bytes: number;
readonly retained_bytes: number;
};
readonly output_closed: boolean;
readonly diagnostic_truncated: boolean;
};
/** Hopper did not respond within the configured operation deadline. */
export class HopperTimeoutError extends HopperError {
readonly _tag = "HopperTimeoutError";
constructor(
readonly timeoutMs: number,
readonly operation?: string,
readonly requestId?: number,
readonly providerState: "busy" | "not_started" = "not_started",
readonly stage: ProviderFailureStage = operation === undefined
? "launch"
: "analysis",
readonly launcherOutcome?: HopperLauncherOutcome,
) {
super(
`Hopper ${operation === undefined ? "startup" : operation} timed out after ${String(timeoutMs)}ms`,
);
}
}
/** The caller cancelled a Hopper operation before it completed. */
export class HopperCancelledError extends HopperError {
readonly _tag = "HopperCancelledError";
constructor() {
super("Hopper operation was cancelled");
}
}
/** Hopper returned bytes or JSON that do not satisfy the NDJSON RPC contract. */
export class HopperProtocolError extends HopperError {
readonly _tag = "HopperProtocolError";
}
export type HopperDiagnosticType =
| "remote"
| "authorization"
| "invalid_request"
| "capability_unavailable"
| "bridge_exception";
/** Hopper's JSON-RPC endpoint returned an expected remote error response. */
export interface HopperRemoteErrorContext extends AnalysisErrorOptions {
readonly diagnosticType?: HopperDiagnosticType | undefined;
readonly operation?: string | undefined;
readonly requestId?: number | undefined;
}
export class HopperRemoteError extends HopperError {
readonly _tag = "HopperRemoteError";
readonly diagnosticType: HopperDiagnosticType;
readonly operation: string | undefined;
readonly requestId: number | undefined;
constructor(
readonly code: number,
readonly safeMessage: string,
context: HopperRemoteErrorContext = {},
) {
super(`Hopper request failed (${String(code)}): ${safeMessage}`, context);
this.diagnosticType = context.diagnosticType ?? "remote";
this.operation = context.operation;
this.requestId = context.requestId;
}
}
/** The owned Hopper bridge stopped before its client was closed. */
export interface HopperProcessErrorContext extends AnalysisErrorOptions {
readonly diagnostic?: HopperStartupFailureDiagnostic | undefined;
readonly operation?: string | undefined;
readonly requestId?: number | undefined;
readonly providerState?: HopperProcessProviderState | undefined;
readonly stage?: ProviderFailureStage | undefined;
readonly launcherFailure?: HopperLauncherOutcome | undefined;
}
export class HopperProcessError extends HopperError {
readonly _tag = "HopperProcessError";
readonly failureCode: HopperStartupFailureCode | undefined;
override readonly userMessage: string | undefined;
readonly providerState: HopperProcessProviderState;
readonly stage: ProviderFailureStage;
readonly diagnostic: HopperStartupFailureDiagnostic | undefined;
readonly operation: string | undefined;
readonly requestId: number | undefined;
readonly launcherFailure: HopperLauncherOutcome | undefined;
constructor(
readonly exitCode: number | null,
context: HopperProcessErrorContext = {},
) {
super(
`Hopper bridge stopped unexpectedly with code ${String(exitCode)}`,
context,
);
this.diagnostic = context.diagnostic;
this.operation = context.operation;
this.requestId = context.requestId;
this.launcherFailure = context.launcherFailure;
const failure = hopperStartupFailure(exitCode);
this.stage =
context.stage ??
(failure === undefined
? context.operation === undefined
? "connection"
: "analysis"
: "launch");
this.failureCode = failure?.code;
this.userMessage = failure?.message;
this.providerState =
context.providerState ?? (exitCode === null ? "unknown" : "exited");
}
}
/** Hopper or the repository bridge could not be started. */
export class HopperStartError extends HopperError {
readonly _tag = "HopperStartError";
override readonly userMessage: string | undefined;
readonly ownerRunId: string | undefined;
readonly launcherFailure: HopperLauncherOutcome | undefined;
constructor(
options?: ErrorOptions & {
readonly userMessage?: string;
readonly ownerRunId?: string;
readonly launcherFailure?: HopperLauncherOutcome;
},
) {
super("Hopper application bridge could not be started", options);
this.userMessage = options?.userMessage;
this.ownerRunId = options?.ownerRunId;
this.launcherFailure = options?.launcherFailure;
}
}