refactor(cli)!: name a failure's per-call control flag at the CLI boundary (#11413)

* refactor(cli)!: name a failure's per-call control flag at the CLI boundary

Services name the contract field a deadline failure reports in
details.limit.parameter; a contract command's output projection adds
details.limit.cli_flag from the command's own field-to-flag binding.

BREAKING CHANGE: MCP failures no longer carry details.limit.cli_flag, and
native deadline remediation text no longer names the CLI flag. CLI output
still reports cli_flag for the command that ran.

* fix(cli): key nested flattened members by their dotted path; restore the test's exit status

* refactor(reverse): bind command_timeout_ms as the per-call control of an objdump or Rizin deadline (#11442)

* refactor(reverse): bind command_timeout_ms as the per-call control of an objdump or Rizin deadline

The deadline failure now comes from nativeDeadlineRecovery: it names command_timeout_ms and carries limit {control_kind: "parameter"}, so the CLI projection adds --command-timeout-ms and MCP output names the field only. The service no longer writes CLI flag text.

* refactor(wasm): bind max_artifact_paths as the per-call control of an auxiliary path admission refusal (#11444)
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 04:21:46 +08:00
1 parent 23eee86bd5
commit 49d4991a18
18 files changed
+321 -45

No files matched your search

@@ -1,5 +1,5 @@
import { HOST_PLATFORM } from "../../platform/HostPlatform.js";
import { MAX_NODE_TIMER_DELAY_MS } from "../../domain/analysisResourceLimits.js";
import { nativeDeadlineRecovery } from "../../domain/native/nativeDeadlines.js";
import { Budget } from "../../domain/budget.js";
import {
ArtifactResourceScope,
@@ -1459,17 +1459,20 @@ const runtimeControlPreparationError = (
return windowsNativeSpawnControlError(cause);
};
const reverseCommandTimeoutGuidance = (
provider: string,
timeoutMs: number,
): { readonly userMessage: string; readonly remediationAction: string } => ({
userMessage: `This ${provider} command reached its ${String(timeoutMs)} ms server/provider deadline (command_timeout_ms) during target preflight or the one-shot command (deadlineExpired). This is not a Ghidra or Hopper startup deadline and not a debugger session deadline.`,
remediationAction: `${
timeoutMs < MAX_NODE_TIMER_DELAY_MS
? `Increase command_timeout_ms above ${String(timeoutMs)} (integer milliseconds from 1 to ${String(MAX_NODE_TIMER_DELAY_MS)}; omitted means ${String(DEFAULT_REVERSE_COMMAND_TIMEOUT_MS)}), or use --command-timeout-ms on the CLI.`
: `command_timeout_ms is already at the maximum ${String(MAX_NODE_TIMER_DELAY_MS)} ms; no higher deadline is supported.`
} The new value applies on the next call; no restart is required. The combined output allowance is separately selected by max_output_bytes (default ${String(DEFAULT_REVERSE_COMMAND_OUTPUT_BYTES)} bytes). Allow execution, cleanup and delivery headroom in the outer MCP client deadline. Confirm outstanding work and cleanup before retrying.`,
});
/**
* The deadline failure names `command_timeout_ms` and binds it as the
* per-call control; each adapter names the option that sets it.
*/
const reverseCommandTimeoutGuidance = (provider: string, timeoutMs: number) =>
nativeDeadlineRecovery({
timeoutMs,
parameter: "command_timeout_ms",
defaultMs: DEFAULT_REVERSE_COMMAND_TIMEOUT_MS,
phase: `${provider} command deadline`,
unchanged: `No restart is required. The combined output allowance is separately selected by max_output_bytes (default ${String(DEFAULT_REVERSE_COMMAND_OUTPUT_BYTES)} bytes).`,
detail:
" It covers target preflight and the one-shot command (deadlineExpired); it is not a Ghidra or Hopper startup deadline or a debugger session deadline.",
});
export const digestFile = async (
path: string,
+11 -1
View File
@@ -74,7 +74,17 @@ export class WasmArtifactService {
},
{
retryable: false,
remediationAction: `Raise max_artifact_paths to at least ${String(input.value[field].length)} (maximum ${String(MAX_WASM_ARTIFACT_PATHS)}), or use --max-artifact-paths on the CLI; then retry the same selection. The value applies on the next inspection without restart. File and command byte budgets remain independent.`,
remediationAction: `Raise max_artifact_paths to at least ${String(input.value[field].length)} (maximum ${String(MAX_WASM_ARTIFACT_PATHS)}); then retry the same selection. The value applies on the next inspection without restart. File and command byte budgets remain independent.`,
limit: {
control_kind: "parameter",
parameter: "max_artifact_paths",
effective_value: maximumPaths,
unit: "count",
minimum: 1,
maximum: MAX_WASM_ARTIFACT_PATHS,
default_value: DEFAULT_WASM_ARTIFACT_PATHS,
applies_at: "next_call",
},
},
),
);
+16 -1
View File
@@ -686,11 +686,14 @@ export interface ContractCliDescription {
readonly evidenceTargets: ContractCliEvidenceTargets | undefined;
/**
* Contract fields the CLI spells differently, so input issues reported
* after argv parsing can name the CLI key.
* after argv parsing can name the CLI key, and the flag of each contract
* field (or `field.member`) the command takes as an option, so a failure
* that names a per-call control can name the flag that sets it.
*/
readonly inputBinding: {
readonly operation: string;
readonly fields: Readonly<Record<string, string>>;
readonly flags: Readonly<Record<string, string>>;
};
/** The command adds `--detail` and `--evidence_output`. */
readonly evidenceDelivery: boolean;
@@ -2406,6 +2409,18 @@ export const describeContractCommand = <
...(evidenceTargets?.targets ?? []),
].flatMap(({ field, key }) => (key === field ? [] : [[field, key]])),
),
flags: Object.fromEntries(
parameters.flatMap(({ field, key, member, positional, delivery }) =>
positional || delivery
? []
: [
[
member === undefined ? field : [field, ...member].join("."),
`--${kebabCase(key)}`,
],
],
),
),
},
evidenceDelivery,
admit: (values) => {
+5 -1
View File
@@ -384,7 +384,11 @@ export const runOnEvidenceTargets =
error: "Analysis failed",
...projectAnalysisError(retainSources(source.error), "invocation"),
},
{ operation: evidenceTargets.source, fields: { path: key } },
{
operation: evidenceTargets.source,
fields: { path: key },
flags: {},
},
);
sources[field] = source.value;
}
+54 -11
View File
@@ -4,6 +4,8 @@ import type { Result } from "../domain/result.js";
interface CliInputFieldBinding {
readonly operation: string;
readonly fields: Readonly<Record<string, string>>;
/** Each contract field, or `field.member`, the command takes as a flag. */
readonly flags: Readonly<Record<string, string>>;
}
/** Flatten a finalized outcome only when returning the command's JSON output. */
@@ -17,19 +19,39 @@ export const isObject = (
value !== null && typeof value === "object" && !Array.isArray(value);
/**
* Rename only the actionable parameter paths owned by this operation binding
* in a contract command's output: a direct failure, a delivered failure or a
* refused publication. Any other output is returned unchanged.
* Name a contract command's input fields by their CLI spelling in its
* output: a direct failure, a delivered failure or a refused publication.
* 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.
*/
export const projectCliInputFields = <Output>(
output: Output,
binding: CliInputFieldBinding,
): Output => {
const error = output as JsonValue;
if (!isObject(error)) return output;
const details = error.details;
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;
return {
...error,
details: {
...error.details,
...(issues === undefined ? {} : { issues }),
...(limit === undefined ? {} : { limit }),
},
} as Output;
};
/** Issue paths renamed to CLI keys, or undefined when none changes. */
const renamedIssues = (
error: Record<string, JsonValue>,
details: Record<string, JsonValue>,
binding: CliInputFieldBinding,
): JsonValue[] | undefined => {
if (
!isObject(details) ||
details.operation !== binding.operation ||
!Array.isArray(details.issues) ||
(error.code !== "invalid_request" &&
@@ -38,8 +60,7 @@ export const projectCliInputFields = <Output>(
details.execution_failure === "invalid_request"
))
)
return output;
return undefined;
let changed = false;
const issues = details.issues.map((issue) => {
if (!isObject(issue) || !Array.isArray(issue.path)) return issue;
@@ -53,7 +74,29 @@ export const projectCliInputFields = <Output>(
});
// Keep retained output, partial Evidence and cleanup history by reference;
// their source fields are not CLI parameter names.
return changed
? ({ ...error, details: { ...details, issues } } as Output)
: output;
return changed ? issues : undefined;
};
/**
* The reported per-call control with the flag that sets it, or undefined
* when the command takes no flag for it. The longest bound prefix of the
* parameter path names the flag: a flattened member option, else the option
* of the whole field (such as `--producer-limits` JSON).
*/
const flaggedLimit = (
limit: JsonValue | undefined,
binding: CliInputFieldBinding,
): Record<string, JsonValue> | undefined => {
if (
!isObject(limit) ||
limit.control_kind !== "parameter" ||
typeof limit.parameter !== "string"
)
return undefined;
const segments = limit.parameter.split(".");
for (let length = segments.length; length > 0; length -= 1) {
const flag = binding.flags[segments.slice(0, length).join(".")];
if (flag !== undefined) return { ...limit, cli_flag: flag };
}
return undefined;
};
-2
View File
@@ -102,8 +102,6 @@ export type AnalysisControlLimit = {
| {
readonly control_kind: "parameter";
readonly parameter: string;
/** CLI spelling of the same per-call parameter. */
readonly cli_flag: string;
readonly applies_at: "next_call";
}
| {
+2 -4
View File
@@ -75,7 +75,6 @@ export const readNativeDeadline = (
export const nativeDeadlineRecovery = (input: {
readonly timeoutMs: number;
readonly parameter: string;
readonly cliFlag: string;
readonly defaultMs: number;
readonly phase: string;
readonly unchanged: string;
@@ -87,15 +86,14 @@ export const nativeDeadlineRecovery = (input: {
} => {
const atMaximum = input.timeoutMs >= MAX_NODE_TIMER_DELAY_MS;
const adjustment = atMaximum
? `${input.parameter} (${input.cliFlag} on the CLI) is already at the maximum ${String(MAX_NODE_TIMER_DELAY_MS)} ms; do not increase it.`
: `Increase ${input.parameter} above ${String(input.timeoutMs)} (integer milliseconds from 1 to ${String(MAX_NODE_TIMER_DELAY_MS)}; omitted means ${String(input.defaultMs)}), or pass ${input.cliFlag} on the CLI. A change applies on the next call.`;
? `${input.parameter} is already at the maximum ${String(MAX_NODE_TIMER_DELAY_MS)} ms; do not increase it.`
: `Increase ${input.parameter} above ${String(input.timeoutMs)} (integer milliseconds from 1 to ${String(MAX_NODE_TIMER_DELAY_MS)}; omitted means ${String(input.defaultMs)}). A change applies on the next call.`;
return {
userMessage: `This request reached REA's ${input.phase} of ${String(input.timeoutMs)} ms (${input.parameter}). This is a server/provider deadline, not the MCP client deadline.${input.detail ?? ""}`,
remediationAction: `${adjustment} ${input.unchanged} Allow execution, cleanup, and delivery headroom in the outer MCP client deadline. Confirm outstanding work and cleanup before retrying.`,
limit: {
control_kind: "parameter",
parameter: input.parameter,
cli_flag: input.cliFlag,
effective_value: input.timeoutMs,
unit: "ms",
minimum: 1,
@@ -123,7 +123,6 @@ describe("translateNativeCommandFailure", () => {
expect(projectAnalysisError(error).details?.limit).toEqual({
control_kind: "parameter",
parameter: "native_command_timeout_ms",
cli_flag: "--native-command-timeout-ms",
effective_value: 60_000,
unit: "ms",
minimum: 1,
-2
View File
@@ -115,7 +115,6 @@ export const translateNativeCommandFailure = (
nativeDeadlineRecovery({
timeoutMs,
parameter: "native_command_timeout_ms",
cliFlag: "--native-command-timeout-ms",
defaultMs: DEFAULT_NATIVE_COMMAND_TIMEOUT_MS,
phase: "macOS native command deadline",
unchanged: `The ${String(NATIVE_COMMAND_OUTPUT_BUDGET_BYTES)}-byte command output allowance and the ${String(NATIVE_FAILURE_DIAGNOSTIC_BYTES)}-byte failure-diagnostic excerpt have no runtime override.`,
@@ -201,7 +200,6 @@ export const translateNativeCommandFailure = (
nativeDeadlineRecovery({
timeoutMs,
parameter: "native_command_timeout_ms",
cliFlag: "--native-command-timeout-ms",
defaultMs: DEFAULT_NATIVE_COMMAND_TIMEOUT_MS,
phase: "macOS native command deadline",
unchanged: `The ${String(NATIVE_COMMAND_OUTPUT_BUDGET_BYTES)}-byte command output allowance and the ${String(NATIVE_FAILURE_DIAGNOSTIC_BYTES)}-byte failure-diagnostic excerpt have no runtime override.`,
@@ -92,7 +92,6 @@ export class NativeUiInterruptionControl {
...nativeDeadlineRecovery({
timeoutMs: this.#deadlineMs,
parameter: "native_ui_deadline_ms",
cliFlag: "--native-ui-deadline-ms",
defaultMs: DEFAULT_NATIVE_UI_DEADLINE_MS,
phase: "native UI observation deadline",
detail: " A partial observation may already be retained.",
@@ -121,7 +121,6 @@ it("distinguishes the wall deadline from caller-selected producer resource budge
expect(projected.details?.limit).toMatchObject({
control_kind: "parameter",
parameter: "pwntools_timeout_ms",
cli_flag: "--pwntools-timeout-ms",
effective_value: 4_500,
default_value: 30_000,
});
-1
View File
@@ -227,7 +227,6 @@ const pwntoolsCommandContext = (
const deadline = nativeDeadlineRecovery({
timeoutMs,
parameter: "pwntools_timeout_ms",
cliFlag: "--pwntools-timeout-ms",
defaultMs: PWNTOOLS_LIMITS.command_timeout_ms,
phase: "pwntools command deadline",
unchanged: budgetRecovery,