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:
morluto
2026-10-12 02:13:53 +08:00
committed by GitHub
parent dfe31172ca
commit 601814ed0e
17 changed files with 339 additions and 263 deletions
+3 -3
View File
@@ -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. */
+4 -1
View File
@@ -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"
+5 -2
View File
@@ -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
View File
@@ -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");
}
}
+3 -4
View File
@@ -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,
}),
};
}
}
+1 -3
View File
@@ -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
View File
@@ -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),
}),
);
}
}
+18 -19
View File
@@ -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,
});