feat(errors): name the fields a failure's recovery selects so the CLI renders their flags (#11644)

* feat(errors): name the fields a failure's recovery selects so the CLI renders their flags

AnalysisError gains related { parameters, operations } (contract fields and operation names), projected as details.related_parameters / related_operations and kept through the domain re-attribution helpers. The CLI projection adds details.related_cli_flags for its own command's fields. inspect_plist's missing-default failure and inspect_sqlite_database's column-evaluation failure name fields only in their text.

* test(sqlite): check MCP omits CLI flags on the failure that names related fields
This commit is contained in:
morluto authored and GitHub committed 2026-11-15 20:54:50 -05:00
1 parent 2a31e064f3
commit 0035d8edb3
11 files changed
+168 -17

No files matched your search

@@ -6,7 +6,5 @@
"src/ghidra/GhidraFileOffsetFailure.ts": 1,
"src/ghidra/GhidraProviderClient.ts": 5,
"src/javascript/analysis/JavaScriptAnalysisWorker.ts": 1,
"src/kuna/KunaProjectReader.ts": 1,
"src/native/NativePlistSource.ts": 1,
"src/sqlite/SqliteDatabaseWorkerExecution.ts": 1
"src/kuna/KunaProjectReader.ts": 1
}
+32 -2
View File
@@ -27,7 +27,9 @@ export const isObject = (
* Issue paths owned by this operation take the CLI key, and a per-call
* control a failure reports (`details.limit.parameter`, which services name
* by contract field) gains `cli_flag`, the option that sets it on this
* command. Any other output is returned unchanged.
* command, and the fields its recovery names (`details.related_parameters`)
* gain `related_cli_flags`, each field's option. Any other output is returned
* unchanged.
*/
export const projectCliInputFields = <Output>(
output: Output,
@@ -37,17 +39,45 @@ export const projectCliInputFields = <Output>(
if (!isObject(error) || !isObject(error.details)) return output;
const issues = renamedIssues(error, error.details, binding);
const limit = flaggedLimit(error.details.limit, binding);
if (issues === undefined && limit === undefined) return output;
const relatedFlags = relatedCliFlags(error.details, binding);
if (issues === undefined && limit === undefined && relatedFlags === undefined)
return output;
return {
...error,
details: {
...error.details,
...(issues === undefined ? {} : { issues }),
...(limit === undefined ? {} : { limit }),
...(relatedFlags === undefined
? {}
: { related_cli_flags: relatedFlags }),
},
} as Output;
};
/**
* The option of each field this command's failure names for its recovery,
* keyed by contract field, or undefined when it takes none of them. Fields
* of another operation are that command's to render.
*/
const relatedCliFlags = (
details: Record<string, JsonValue>,
binding: CliInputFieldBinding,
): Record<string, JsonValue> | undefined => {
if (
details.operation !== binding.operation ||
!Array.isArray(details.related_parameters)
)
return undefined;
const flags: Record<string, JsonValue> = {};
for (const parameter of details.related_parameters) {
if (typeof parameter !== "string") continue;
const flag = cliFlagFor(parameter, binding);
if (flag !== undefined) flags[parameter] = flag;
}
return Object.keys(flags).length === 0 ? undefined : flags;
};
/** Issue paths renamed to CLI keys, or undefined when none changes. */
const renamedIssues = (
error: Record<string, JsonValue>,
+27
View File
@@ -94,6 +94,18 @@ export interface AnalysisContinuingCallerGuidance {
readonly remediationAction?: string;
}
/**
* Inputs a failure's recovery names: fields of the failing operation's
* contract (`path`, or `field.member`) the caller may set instead, and other
* operations, by contract name, the caller may call. Each adapter renders its
* own spelling (a CLI flag or command, an MCP field or tool), so the
* message and remediation name contract fields and operations only.
*/
export interface AnalysisRelatedInputs {
readonly parameters?: readonly string[];
readonly operations?: readonly string[];
}
/** Optional provider-neutral context that must survive typed error projection. */
export interface AnalysisErrorOptions extends ErrorOptions {
/** Typed primary retained when a later lifecycle failure composes this error. */
@@ -101,6 +113,8 @@ export interface AnalysisErrorOptions extends ErrorOptions {
/** Producer-owned, caller-safe facts retained through every typed projection. */
readonly diagnostics?: Readonly<Record<string, JsonValue>> | undefined;
readonly limit?: AnalysisLimit | undefined;
/** Inputs the recovery names, rendered by each adapter. */
readonly related?: AnalysisRelatedInputs | undefined;
readonly continuingCallerGuidance?:
| AnalysisContinuingCallerGuidance
| undefined;
@@ -188,6 +202,8 @@ export abstract class AnalysisError extends Error {
| { readonly cleanupResources: readonly string[] }
| undefined;
readonly diagnostics: Readonly<Record<string, JsonValue>> | undefined;
/** Inputs the recovery names, rendered by each adapter. */
readonly related: Readonly<AnalysisRelatedInputs> | undefined;
readonly continuingCallerGuidance:
| Readonly<AnalysisContinuingCallerGuidance>
| undefined;
@@ -216,6 +232,17 @@ export abstract class AnalysisError extends Error {
super(message, options);
this.#cleanupPrimary = options?.cleanupPrimary;
if (options?.limit !== undefined) this.bindLimit(options.limit);
this.related =
options?.related === undefined
? undefined
: Object.freeze({
...(options.related.parameters === undefined
? {}
: { parameters: Object.freeze([...options.related.parameters]) }),
...(options.related.operations === undefined
? {}
: { operations: Object.freeze([...options.related.operations]) }),
});
this.diagnostics =
options?.diagnostics === undefined
? undefined
+2
View File
@@ -134,6 +134,8 @@ export const reattributedResourceConstraint = (
...options,
...resourceConstraintRecovery(error),
...(error.limit === undefined ? {} : { limit: error.limit }),
...(error.related === undefined ? {} : { related: error.related }),
...(error.requestSent === undefined
? {}
: { requestSent: error.requestSent }),
+17
View File
@@ -57,6 +57,7 @@ import {
type AnalysisCallerLifetime,
type AnalysisError,
type AnalysisErrorOptions,
type AnalysisRelatedInputs,
type AnalysisErrorTag,
} from "./analysisErrorBase.js";
import { invocationLimit } from "./analysisSettingDefinitions.js";
@@ -71,6 +72,21 @@ import { isRecord } from "../kernel/isRecord.js";
* releases its provider session and runtime after this request, such as a
* one-shot CLI command, passes `"invocation"`.
*/
/**
* Inputs the recovery names, by contract field and operation name. Each
* adapter renders them in its own spelling.
*/
const relatedInputDetails = (
related: AnalysisRelatedInputs | undefined,
): Record<string, JsonValue> => ({
...(related?.parameters === undefined || related.parameters.length === 0
? {}
: { related_parameters: [...related.parameters] }),
...(related?.operations === undefined || related.operations.length === 0
? {}
: { related_operations: [...related.operations] }),
});
export const projectAnalysisError = (
error: AnalysisError,
callerLifetime: AnalysisCallerLifetime = "continuing",
@@ -438,6 +454,7 @@ const projectError = (
...(refusal === undefined
? {}
: { refusal: analysisRefusalDetails(refusal) }),
...relatedInputDetails(primary.related),
...(!options.secondary || secondary.size === 0
? {}
: {
+6
View File
@@ -147,6 +147,8 @@ const redactFailure = (
const context = {
cause: error,
...(error.limit === undefined ? {} : { limit: error.limit }),
...(error.related === undefined ? {} : { related: error.related }),
...(guidance === undefined
? {}
: {
@@ -246,6 +248,8 @@ const redactFailure = (
? {}
: { remediationAction: text(error.remediationAction) }),
...(error.limit === undefined ? {} : { limit: error.limit }),
...(error.related === undefined ? {} : { related: error.related }),
});
if (error instanceof AnalysisAccessDeniedError)
return new AnalysisAccessDeniedError(
@@ -331,6 +335,8 @@ const redactFailure = (
...context,
...resourceConstraintRecovery(error, text),
...(error.limit === undefined ? {} : { limit: error.limit }),
...(error.related === undefined ? {} : { related: error.related }),
...(error.requestSent === undefined
? {}
: { requestSent: error.requestSent }),
+6 -2
View File
@@ -125,12 +125,16 @@ export const unreadablePlist = (
switch (selection.origin) {
case "default": {
// Name the default that is missing and the selection that still works.
const missingDefault = `The target has no readable default plist at ${path}: ${sentence} Select another plist in the target with the path input (CLI: --relative-path).`;
const missingDefault = `The target has no readable default plist at ${path}: ${sentence} Select another plist in the target with the path input.`;
return new AnalysisCapabilityUnavailableError(
IDENTITY.id,
"inspect_plist",
missingDefault,
{ ...options, userMessage: missingDefault },
{
...options,
userMessage: missingDefault,
related: { parameters: ["path"] },
},
);
}
case "target":
+2 -1
View File
@@ -119,10 +119,11 @@ const rejectedReply = (
{
capturedOutput,
userMessage: reply.message,
related: { parameters: ["columns", "table", "schema_scope"] },
remediationAction: `The database is readable; only the listed column values failed. REA's SQLite connection loads no extensions or application functions and disables schema trust. ${
readable.length === 0
? "No other readable column was found"
: `Select columns whose values were read: columns: ${JSON.stringify(readable)} (CLI: one --column per name)`
: `Select columns whose values were read: columns: ${JSON.stringify(readable)}`
}; omit table and use schema_scope: database to read the stored declarations without evaluating rows. Obtaining the failed values needs a SQLite connection able to evaluate them. Do not repeat the unchanged request.`,
},
);
+23 -4
View File
@@ -273,7 +273,8 @@ for (const expectedErrno of ["ELOOP", "ENAMETOOLONG"] as const) {
expect(result.json).toMatchObject(expectedError);
const { call } = await connectLocalToolsMcp();
const response = await call("inspect_sqlite_database", { path });
expect(parseMcpToolError(response).error).toMatchObject(expectedError);
const mcpError = parseMcpToolError(response).error;
expect(mcpError).toMatchObject(expectedError);
},
);
}
@@ -1258,10 +1259,14 @@ cliTest.runIf(SQLITE_NATIVE_LIMITS_AVAILABLE)(
code: "capability_unavailable",
retryable: false,
message,
details: { provider_id: "sqlite", reason: message },
details: {
provider_id: "sqlite",
reason: message,
related_parameters: ["columns", "table", "schema_scope"],
},
remediation: {
action: expect.stringContaining(
'Select columns whose values were read: columns: ["a"] (CLI: one --column per name)',
'Select columns whose values were read: columns: ["a"];',
),
},
};
@@ -1279,13 +1284,27 @@ cliTest.runIf(SQLITE_NATIVE_LIMITS_AVAILABLE)(
});
expect(result.exitCode, result.stdout + result.stderr).toBe(1);
expect(result.json).toMatchObject(expectedError);
// The CLI renders each named field's flag; MCP output names fields only.
expect(result.json).toMatchObject({
details: {
related_cli_flags: {
columns: "--column",
table: "--table",
schema_scope: "--schema-scope",
},
},
});
expect(result.stdout).not.toContain("invalid_format");
const response = await call("inspect_sqlite_database", {
path,
table: "t",
...(columns === undefined ? {} : { columns }),
});
expect(parseMcpToolError(response).error).toMatchObject(expectedError);
const mcpError = parseMcpToolError(response).error;
expect(mcpError).toMatchObject(expectedError);
// MCP names the related fields only; flags are the CLI's spelling.
expect(mcpError.details).not.toHaveProperty("related_cli_flags");
expect(JSON.stringify(mcpError)).not.toContain("--column");
}
const base = await cli.run({
arguments: [
@@ -136,14 +136,17 @@ describe.skipIf(process.platform !== "darwin")(
expect(result.exitCode).toBe(1);
expect(result.json).toMatchObject({
code: "capability_unavailable",
message: expect.stringContaining("(CLI: --relative-path)"),
message: expect.stringMatching(
/select another plist.*with the path input\.$/iu,
),
remediation: {
action: expect.stringMatching(
/select another plist.*path input.*--relative-path/iu,
),
action: expect.stringMatching(/select another plist.*path input/iu),
},
details: {
operation: "inspect_plist",
// The message names the contract field; the CLI renders its flag.
related_parameters: ["path"],
related_cli_flags: { path: "--relative-path" },
reason: expect.stringContaining(
`no readable default plist at ${join(directory, "Contents/Info.plist")}: no file exists there.`,
),
@@ -1,6 +1,10 @@
import { expect, it } from "vitest";
import { AnalysisInputError } from "../../../src/domain/analysisErrorCore.js";
import {
AnalysisInputError,
AnalysisResourceConstraintError,
reattributedResourceConstraint,
} from "../../../src/domain/analysisErrorCore.js";
import { analysisErrorWithCleanupFailure } from "../../../src/domain/analysisErrorCleanup.js";
import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
import { freezeJsonSnapshot } from "../../../src/domain/immutableJson.js";
@@ -139,3 +143,43 @@ it("passes through successful data, unbound operations and unknown error values"
};
expect(projectCliInputFields(unknown, binding)).toBe(unknown);
});
it("names related fields and operations by contract identity and renders only this command's flags", () => {
const constraint = new AnalysisResourceConstraintError(
"inspect_sqlite_database",
"memory",
"fixture limit",
null,
{
related: {
parameters: ["columns", "table", "row_limit"],
operations: ["inspect_artifact"],
},
},
);
// Re-attribution keeps the inputs the recovery names, as it keeps `limit`.
const projected = projectAnalysisError(
reattributedResourceConstraint("inspect_sqlite_database", constraint),
);
expect(projected.details).toMatchObject({
related_parameters: ["columns", "table", "row_limit"],
related_operations: ["inspect_artifact"],
});
const sqlite = {
operation: "inspect_sqlite_database",
fields: {},
flags: { columns: "--column", table: "--table" },
};
// A field the command takes no flag for is left to the contract name.
expect(projectCliInputFields(projected, sqlite)).toMatchObject({
details: { related_cli_flags: { columns: "--column", table: "--table" } },
});
// Another command's failure keeps its fields for that command to render.
expect(
projectCliInputFields(projected, { ...sqlite, operation: "inspect_plist" }),
).toBe(projected);
// An error that names nothing projects no related fields.
expect(
projectAnalysisError(new AnalysisInputError("inspect_plist")).details ?? {},
).not.toHaveProperty("related_parameters");
});