From 0da36910dcbd8cdcf405ed9270c5e71b9342d9ce Mon Sep 17 00:00:00 2001 From: ShuaixinHuang <1836656514@qq.com> Date: Thu, 22 Oct 2026 04:07:28 +0800 Subject: [PATCH] docs(artifacts): clarify unsupported DMG extraction (#5555) * docs(artifacts): clarify unsupported DMG extraction * fix(cli): keep the WASM command timeout optional * fix(cli): preserve WASM timeout help metadata * test(pe): reuse compiled CLI startup for resource acceptance * fix(cli): use upstream exact-optional timeout semantics --- .../references/native-and-artifacts.md | 11 +++++++---- src/cli/artifactCommands.ts | 3 ++- src/contracts/artifactToolContracts.ts | 4 ++-- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md index 896378dc9a..4e549ce493 100644 --- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -345,8 +345,8 @@ every executable in the bundle. It also lists missing or weak loads and earlier `architecture`. System paths stay undetermined because the dyld shared cache provides them. -Use `extract_artifact` when materialized files are needed. It extracts the active -target and accepts optional `integrity_policy`; see the [MCP contracts](https://github.com/morluto/rea/blob/main/docs/mcp-contracts.md). +Use `extract_artifact` when materialized files from a supported format are needed. +It extracts the active target and accepts optional `integrity_policy`; see the [MCP contracts](https://github.com/morluto/rea/blob/main/docs/mcp-contracts.md). It materializes all regular files into a fresh temporary directory chosen by REA. Symlinks and encrypted entries are inventory facts, not extractable files. The result reports the materialized directory; callers do not choose the @@ -355,8 +355,11 @@ destination. No separate permission grant is needed. Native DMG traversal automatically uses a read-only mount on supported macOS hosts, with an owned temporary mount directory and cleanup. It needs no approval flag. Unsupported hosts or mount failures remain explicit limitations; do not -claim child inventory when only root identity is available. Extraction is a -separate filesystem-writing operation. +claim child inventory when only root identity is available. DMG extraction is +unavailable through `extract_artifact`. To access DMG files on macOS, create a +read-only mount with your own tools, select files from that mount for analysis, +and detach the mount you created when finished. REA's inspection mount is +temporary, not a retained export of the image's contents. For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI `--target-format dos-com`). Inspect the load image before trusting function diff --git a/src/cli/artifactCommands.ts b/src/cli/artifactCommands.ts index 46458e8581..7082b27da6 100644 --- a/src/cli/artifactCommands.ts +++ b/src/cli/artifactCommands.ts @@ -199,7 +199,8 @@ const registerExtractionCommand = ( runProviderAnalysis: DirectAnalysis["runProviderAnalysis"], ): void => { cli.command(CLI_COMMANDS.extractArtifact, { - description: "Extract all regular artifact contents safely", + description: + "Extract regular contents of supported artifacts; DMG extraction is unavailable", args: z.object({ path: z.string().describe("Application or package path"), }), diff --git a/src/contracts/artifactToolContracts.ts b/src/contracts/artifactToolContracts.ts index afb8a10de4..773f1ef47a 100644 --- a/src/contracts/artifactToolContracts.ts +++ b/src/contracts/artifactToolContracts.ts @@ -80,12 +80,12 @@ const artifact = < export const ARTIFACT_TOOL_CONTRACTS = [ artifact( "inspect_artifact", - "Inspect an active archive or application package in one call. By default returns the complete content-addressed artifact graph once, as the typed nested inventory Evidence, with root and integrity observations, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. For PCK and large containers prefer detail summary: it retains the complete inspection and returns its derived summary view; read exact paths, batch occurrence/content IDs and selected fields with inspect_analysis_view using parent_evidence_id. This changes delivery, not inventory coverage. Read-only DMG mounting is used automatically on supported macOS hosts. Integrity mismatches fail by default; record-and-continue keeps mismatches explicitly untrusted. It does not extract files; use extract_artifact to materialize its regular contents.", + "Inspect an active archive or application package in one call. By default returns the complete content-addressed artifact graph once, as the typed nested inventory Evidence, with root and integrity observations, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. For PCK and large containers prefer detail summary: it retains the complete inspection and returns its derived summary view; read exact paths, batch occurrence/content IDs and selected fields with inspect_analysis_view using parent_evidence_id. This changes delivery, not inventory coverage. Read-only DMG mounting is used automatically on supported macOS hosts. Integrity mismatches fail by default; record-and-continue keeps mismatches explicitly untrusted. It does not extract files; use extract_artifact to materialize regular contents of supported formats. DMG extraction is unavailable; use a caller-managed read-only mount on macOS to access its files.", artifactInspectionInputSchema, ), artifact( "extract_artifact", - "Extract all regular files from the active archive or application package into a fresh temporary directory chosen by REA. The result includes its location. Rejects traversal and symlink escapes, never overwrites, and verifies cleanup. Integrity mismatches fail by default; record-and-continue extracts the observed bytes and returns each mismatch as an explicitly untrusted integrity contradiction.", + "Extract all regular files from a supported active archive or application package into a fresh temporary directory chosen by REA. The result includes its location. DMG extraction is unavailable; use a caller-managed read-only mount on macOS to access its files. Rejects traversal and symlink escapes, never overwrites, and verifies cleanup. Integrity mismatches fail by default; record-and-continue extracts the observed bytes and returns each mismatch as an explicitly untrusted integrity contradiction.", artifactExtractionInputSchema, ), artifact(