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
This commit is contained in:
@@ -51,9 +51,9 @@ export interface AnalysisCleanupObservation {
|
||||
|
||||
/** Optional provider-neutral context that must survive typed error projection. */
|
||||
export interface AnalysisErrorOptions extends ErrorOptions {
|
||||
readonly capturedOutput?: AnalysisCapturedOutput;
|
||||
readonly cleanup?: AnalysisCleanupObservation;
|
||||
readonly partialObservation?: AnalysisPartialObservation;
|
||||
readonly capturedOutput?: AnalysisCapturedOutput | undefined;
|
||||
readonly cleanup?: AnalysisCleanupObservation | undefined;
|
||||
readonly partialObservation?: AnalysisPartialObservation | undefined;
|
||||
}
|
||||
|
||||
/** Base class for expected analysis, provider, and session failures. */
|
||||
|
||||
@@ -265,9 +265,12 @@ const hopperProcessMessage = (error: HopperProcessError): string => {
|
||||
const startup =
|
||||
error.userMessage === undefined ? "" : ` ${error.userMessage}`;
|
||||
if (error.providerState === "exited") {
|
||||
const signal = error.launcherFailure?.signal;
|
||||
const exit =
|
||||
error.exitCode === null
|
||||
? "no exit code was observed"
|
||||
? signal === undefined || signal === null
|
||||
? "no exit code was observed"
|
||||
: `signal ${signal}`
|
||||
: `exit code ${String(error.exitCode)}`;
|
||||
const recovery =
|
||||
error.failureCode === undefined && stage !== "launch"
|
||||
|
||||
@@ -572,7 +572,7 @@ describe("analysis error projection: caller contract", () => {
|
||||
describe("analysis error projection: operational diagnostics", () => {
|
||||
it("distinguishes an observed Hopper exit from an undetermined provider failure", () => {
|
||||
const exited = projectAnalysisError(
|
||||
new HopperProcessError(7, undefined, "search_strings", 4),
|
||||
new HopperProcessError(7, { operation: "search_strings", requestId: 4 }),
|
||||
);
|
||||
expect(exited).toMatchObject({
|
||||
code: "provider_unavailable",
|
||||
@@ -590,7 +590,10 @@ describe("analysis error projection: operational diagnostics", () => {
|
||||
expect(exited.remediation.action).toContain("Restart the owned provider");
|
||||
|
||||
const unknown = projectAnalysisError(
|
||||
new HopperProcessError(null, undefined, "search_strings", 5),
|
||||
new HopperProcessError(null, {
|
||||
operation: "search_strings",
|
||||
requestId: 5,
|
||||
}),
|
||||
);
|
||||
expect(unknown.details).toMatchObject({
|
||||
stage: "analysis",
|
||||
|
||||
+34
-16
@@ -1,4 +1,7 @@
|
||||
import { AnalysisError } from "./analysisErrorBase.js";
|
||||
import {
|
||||
AnalysisError,
|
||||
type AnalysisErrorOptions,
|
||||
} from "./analysisErrorBase.js";
|
||||
import type {
|
||||
HopperProcessProviderState,
|
||||
ProviderFailureStage,
|
||||
@@ -73,10 +76,10 @@ export type HopperDiagnosticType =
|
||||
| "bridge_exception";
|
||||
|
||||
/** Hopper's JSON-RPC endpoint returned an expected remote error response. */
|
||||
export interface HopperRemoteErrorContext {
|
||||
readonly diagnosticType?: HopperDiagnosticType;
|
||||
readonly operation?: string;
|
||||
readonly requestId?: number;
|
||||
export interface HopperRemoteErrorContext extends AnalysisErrorOptions {
|
||||
readonly diagnosticType?: HopperDiagnosticType | undefined;
|
||||
readonly operation?: string | undefined;
|
||||
readonly requestId?: number | undefined;
|
||||
}
|
||||
|
||||
export class HopperRemoteError extends HopperError {
|
||||
@@ -90,7 +93,7 @@ export class HopperRemoteError extends HopperError {
|
||||
readonly safeMessage: string,
|
||||
context: HopperRemoteErrorContext = {},
|
||||
) {
|
||||
super(`Hopper request failed (${String(code)}): ${safeMessage}`);
|
||||
super(`Hopper request failed (${String(code)}): ${safeMessage}`, context);
|
||||
this.diagnosticType = context.diagnosticType ?? "remote";
|
||||
this.operation = context.operation;
|
||||
this.requestId = context.requestId;
|
||||
@@ -98,35 +101,50 @@ export class HopperRemoteError extends HopperError {
|
||||
}
|
||||
|
||||
/** 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,
|
||||
readonly diagnostic?: HopperStartupFailureDiagnostic,
|
||||
readonly operation?: string,
|
||||
readonly requestId?: number,
|
||||
providerState?: HopperProcessProviderState,
|
||||
stage?: ProviderFailureStage,
|
||||
readonly launcherFailure?: HopperLauncherOutcome,
|
||||
context: HopperProcessErrorContext = {},
|
||||
) {
|
||||
super(`Hopper bridge stopped unexpectedly with code ${String(exitCode)}`);
|
||||
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 =
|
||||
stage ??
|
||||
context.stage ??
|
||||
(failure === undefined
|
||||
? operation === undefined
|
||||
? context.operation === undefined
|
||||
? "connection"
|
||||
: "analysis"
|
||||
: "launch");
|
||||
this.failureCode = failure?.code;
|
||||
this.userMessage = failure?.message;
|
||||
this.providerState =
|
||||
providerState ?? (exitCode === null ? "unknown" : "exited");
|
||||
context.providerState ?? (exitCode === null ? "unknown" : "exited");
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -362,10 +362,9 @@ export class HopperApplicationLauncher implements BridgeLauncher {
|
||||
? { ok: true, strategy: selection.strategy }
|
||||
: {
|
||||
ok: false,
|
||||
error: new HopperProcessError(
|
||||
selection.exitCode,
|
||||
selection.diagnostic,
|
||||
),
|
||||
error: new HopperProcessError(selection.exitCode, {
|
||||
diagnostic: selection.diagnostic,
|
||||
}),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
@@ -202,9 +202,7 @@ const shutdownRequestFailure = (
|
||||
operation: "shutdown" | "shutdown_document",
|
||||
cause: unknown,
|
||||
): HopperProcessError => {
|
||||
const failure = new HopperProcessError(null, undefined, operation);
|
||||
failure.cause = cause;
|
||||
return failure;
|
||||
return new HopperProcessError(null, { operation, cause });
|
||||
};
|
||||
|
||||
const shutdownFailureDetails = (
|
||||
|
||||
+44
-44
@@ -129,13 +129,9 @@ export class HopperClient {
|
||||
this.#responses.push(chunk);
|
||||
};
|
||||
readonly #onSocketError = (): void => {
|
||||
const error = new HopperProcessError(
|
||||
null,
|
||||
undefined,
|
||||
undefined,
|
||||
undefined,
|
||||
"unreachable",
|
||||
);
|
||||
const error = new HopperProcessError(null, {
|
||||
providerState: "unreachable",
|
||||
});
|
||||
this.#failAll(error);
|
||||
this.#rememberProcessFailure(error, []);
|
||||
};
|
||||
@@ -151,25 +147,18 @@ export class HopperClient {
|
||||
setImmediate(() => {
|
||||
if (this.#closing || this.#launcherExitCode !== undefined) return;
|
||||
const exitCode = launch.process.exitCode ?? null;
|
||||
const error = new HopperProcessError(
|
||||
exitCode,
|
||||
this.#launcherFailureDiagnostic,
|
||||
undefined,
|
||||
undefined,
|
||||
exitCode !== null ? "exited" : "unreachable",
|
||||
);
|
||||
const error = new HopperProcessError(exitCode, {
|
||||
diagnostic: this.#launcherFailureDiagnostic,
|
||||
providerState: exitCode !== null ? "exited" : "unreachable",
|
||||
});
|
||||
this.#failAll(error);
|
||||
this.#rememberProcessFailure(error, []);
|
||||
});
|
||||
return;
|
||||
}
|
||||
const error = new HopperProcessError(
|
||||
null,
|
||||
undefined,
|
||||
undefined,
|
||||
undefined,
|
||||
"unreachable",
|
||||
);
|
||||
const error = new HopperProcessError(null, {
|
||||
providerState: "unreachable",
|
||||
});
|
||||
this.#failAll(error);
|
||||
this.#rememberProcessFailure(error, []);
|
||||
};
|
||||
@@ -729,15 +718,12 @@ export class HopperClient {
|
||||
)) ?? false;
|
||||
const launcherFailure = this.#launcherOutcome(outputClosed);
|
||||
if (ownsProviderLifetime)
|
||||
return new HopperProcessError(
|
||||
exitCode,
|
||||
this.#launcherFailureDiagnostic,
|
||||
undefined,
|
||||
undefined,
|
||||
"exited",
|
||||
"launch",
|
||||
return new HopperProcessError(exitCode, {
|
||||
diagnostic: this.#launcherFailureDiagnostic,
|
||||
providerState: "exited",
|
||||
stage: "launch",
|
||||
launcherFailure,
|
||||
);
|
||||
});
|
||||
if (
|
||||
this.#resources.launch?.authorizationDenialBeforeHandoff === true &&
|
||||
nativeHopperLaunchWasDenied(launcherFailure)
|
||||
@@ -766,18 +752,34 @@ export class HopperClient {
|
||||
},
|
||||
): Promise<Result<JsonValue, HopperError>> {
|
||||
const id = this.#nextId++;
|
||||
if (
|
||||
this.#resources.launch?.providerLifetime === "launcher-process" &&
|
||||
this.#launcherExitCode !== undefined
|
||||
) {
|
||||
return this.#unavailableRequest(
|
||||
new HopperProcessError(this.#launcherExitCode, {
|
||||
diagnostic: this.#launcherFailureDiagnostic,
|
||||
operation: method,
|
||||
requestId: id,
|
||||
providerState: "exited",
|
||||
stage: hopperOperationStage(method),
|
||||
launcherFailure: this.#launcherOutcome(
|
||||
(await this.#resources.processSupervisor?.waitForOutputClose(0)) ??
|
||||
false,
|
||||
),
|
||||
}),
|
||||
);
|
||||
}
|
||||
const socket = this.#socket;
|
||||
const token = this.#token;
|
||||
if (socket === undefined || socket.destroyed || token === undefined) {
|
||||
return this.#unavailableRequest(
|
||||
new HopperProcessError(
|
||||
null,
|
||||
undefined,
|
||||
method,
|
||||
id,
|
||||
"unreachable",
|
||||
hopperOperationStage(method),
|
||||
),
|
||||
new HopperProcessError(null, {
|
||||
operation: method,
|
||||
requestId: id,
|
||||
providerState: "unreachable",
|
||||
stage: hopperOperationStage(method),
|
||||
}),
|
||||
);
|
||||
}
|
||||
if (options.signal?.aborted === true)
|
||||
@@ -888,13 +890,11 @@ export class HopperClient {
|
||||
if (launch.providerLifetime === "launcher-process" && !this.#closing) {
|
||||
this.#rememberExit(event.code);
|
||||
this.#failAll(
|
||||
new HopperProcessError(
|
||||
event.code,
|
||||
this.#launcherFailureDiagnostic,
|
||||
undefined,
|
||||
undefined,
|
||||
"exited",
|
||||
),
|
||||
new HopperProcessError(event.code, {
|
||||
diagnostic: this.#launcherFailureDiagnostic,
|
||||
providerState: "exited",
|
||||
launcherFailure: this.#launcherOutcome(false),
|
||||
}),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -273,14 +273,12 @@ export class HopperRequestQueue {
|
||||
this.accept(
|
||||
entry.id,
|
||||
err(
|
||||
new HopperProcessError(
|
||||
null,
|
||||
undefined,
|
||||
entry.method,
|
||||
entry.id,
|
||||
"unreachable",
|
||||
hopperOperationStage(entry.method),
|
||||
),
|
||||
new HopperProcessError(null, {
|
||||
operation: entry.method,
|
||||
requestId: entry.id,
|
||||
providerState: "unreachable",
|
||||
stage: hopperOperationStage(entry.method),
|
||||
}),
|
||||
),
|
||||
),
|
||||
);
|
||||
@@ -386,19 +384,20 @@ const withRequestContext = (
|
||||
entry: QueuedRequest,
|
||||
): HopperError => {
|
||||
if (error instanceof HopperProcessError)
|
||||
return new HopperProcessError(
|
||||
error.exitCode,
|
||||
error.diagnostic,
|
||||
error.operation ?? entry.method,
|
||||
error.requestId ?? entry.id,
|
||||
error.providerState,
|
||||
error.operation === undefined && error.stage === "connection"
|
||||
? hopperOperationStage(entry.method)
|
||||
: error.stage,
|
||||
);
|
||||
return new HopperProcessError(error.exitCode, {
|
||||
...error,
|
||||
cause: error.cause,
|
||||
operation: error.operation ?? entry.method,
|
||||
requestId: error.requestId ?? entry.id,
|
||||
stage:
|
||||
error.operation === undefined && error.stage === "connection"
|
||||
? hopperOperationStage(entry.method)
|
||||
: error.stage,
|
||||
});
|
||||
if (error instanceof HopperRemoteError)
|
||||
return new HopperRemoteError(error.code, error.safeMessage, {
|
||||
diagnosticType: error.diagnosticType,
|
||||
...error,
|
||||
cause: error.cause,
|
||||
operation: error.operation ?? entry.method,
|
||||
requestId: error.requestId ?? entry.id,
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user